From 65a97c099634691fed1c2ee619b74b5cf0254739 Mon Sep 17 00:00:00 2001 From: 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. + * + *

The requirement, in one sentence: there has to be a way back that does not need a build. + * 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. + * + *

The three controls, and why exactly these three. + * + *

+ * + *

Every one of them shouts. 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. + * + *

How they take effect, and why through the properties. 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. + * + *

Deliberately LOCAL, not on-chain. 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 = "", + 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 = "", + 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 = "", + 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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. * + *

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). + * + *

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 falconSeals; + /** AERE ANCHOR V2: the scheme-tagged certificate; empty on every header below the v2 height. */ + private final List 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, final int round, final Collection

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 seals, + final Optional vote, + final int round, + final Collection
validators, + final Collection 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 seals, + final Optional vote, + final int round, + final Collection
validators, + final Collection falconSeals, + final List 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 getFalconSeals() { + return falconSeals; + } + + /** + * The scheme-tagged (v2) certificate. + * + * @return the v2 seals, canonical order; empty below the v2 height + */ + public List 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 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. + * + *

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 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 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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

Configuration (system property takes precedence over environment variable): + * + *

    + *
  • {@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. + *
  • {@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. + *
  • {@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. + *
  • {@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()}). + *
  • {@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). + *
+ * + *

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. + * + *

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 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 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. + * + *

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. + * + *

{@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 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. + * + *

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. + * + *

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 pendingLate; + /** Parsed-but-not-yet-activated validator addresses (validator index -> address). */ + private final Map 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>=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}. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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

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 reg = new ConcurrentHashMap<>(); + final Map regAddr = new ConcurrentHashMap<>(); + String mHash = null; + boolean anchored = false; + Map late = null; + Map 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 pend = new HashMap<>(); + final Map 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 + // ".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 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 {} '.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. + * + *

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. + * + *

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. + * + *

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. + * + *

Only two rules are needed, and the second one implies what the finding is named after: + * + *

    + *
  1. a blocking height over a PENDING late anchor with no declared observation height aborts; + *
  2. {@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. + *
+ * + *

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. + * + *

Rules enforced: + * + *

    + *
  1. a present but MALFORMED or negative attachBlock aborts (no silent degrade); + *
  2. 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; + *
  3. {@code attachBlock > forkBlock} aborts: blocking would arm before any seal exists; + *
  4. {@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; + *
  5. arming BLOCKING with a validator set smaller than {@link #MIN_BLOCKING_VALIDATORS} + * aborts, because at N<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. + *
+ * + * @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. + * + *

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>=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. + * + *

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. + * + *

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. + * + *

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. + * + *

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": + * + *

    + *
  1. 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. + *
  2. 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. + *
  3. 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. + *
+ * + * @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}. + * + *

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}. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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. + * + *

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 outPub, final Map 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 pend, + final Map pendAddr) { + try { + final byte[] raw = Files.readAllBytes(Paths.get(manifestPath)); + final JsonNode root = new ObjectMapper().readTree(raw); + final Map pub = new HashMap<>(); + final Map addr = new HashMap<>(); + final String computed = parseManifest(root, pub, addr); + if (computed == null) { + return null; + } + for (final Map.Entry 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. + * + *

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 reg, + final Map 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 pub = new HashMap<>(); + final Map 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 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> it = alloc.fields(); + while (it.hasNext()) { + final Map.Entry 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> sit = storage.fields(); + while (sit.hasNext()) { + final Map.Entry 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: + * + *

    + *
  • the NEUTRAL name wins when only it is set - new fleets never need the legacy name; + *
  • the LEGACY name still works alone - the live fleet keeps running untouched; + *
  • both set to the SAME value is fine - that is what a migration window looks like; + *
  • 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. + *
+ */ + 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). + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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

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
validators) { + if (!addressBound()) { + return false; + } + final Set
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. + * + *

ON CHAIN 2800 THIS ARMS A RULE THAT IS ALREADY RETIRED, so setting it changes nothing + * (finding D-235, corrected 2026-08-19). 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. + * + *

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. + * + *

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 '.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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

This is deliberately a separate, EARLIER height than {@link #forkBlock()}. The safe ordering + * is: every validator binary upgraded (keyless) -> fleet confirmed on the new binary -> + * attachment height reached, seals start flowing and are verified LOG-ONLY -> 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

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. + * + *

All three conditions are fleet-wide facts, so every correct node flips at the same block: + * + *

    + *
  1. an ATTACHMENT HEIGHT is configured and reached; + *
  2. the anchored Falcon registry is ACTIVE (genesis-anchored, or a late anchor already + * observed on-chain) and address-bound; + *
  3. that registry binds THIS node's own Falcon index to a validator address. + *
+ * + *

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. 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. + * + *

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): + * + *

    + *
  • 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. + *
  • 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. + *
  • 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. + *
  • 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. + *
+ * + *

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. + * + *

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. + * + *

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

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. + * + *

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. + * + *

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. + * + *

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 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 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. + * + *

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. + * + *

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. + * + *

It requires THREE things, and each closes one way of being wrong: + * + *

    + *
  • {@code signingEnabled}: the node holds a key. Without one nothing is emitted, and the + * ECDSA path is not touched in any way. + *
  • {@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. + *
  • its own height, above. + *
+ * + *

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 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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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 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. + * + *

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. + * + *

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 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 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. + * + *

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. + * + *

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 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 nextEntry = + PqRegistryHash.requiredHashAt(schedule, blockNumber + 1); + if (nextEntry.isPresent() && nextEntry.get().block() == blockNumber + 1) { + final Optional 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 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. + * + *

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 nextEntry = + PqRegistryHash.requiredHashAt(schedule, blockNumber + 1); + if (nextEntry.isPresent() && nextEntry.get().block() == blockNumber + 1) { + final Optional 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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 localKeys; + // one shout per missing scheme, not one per block: a permanent alarm is learned and ignored + private final Set 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 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. + * + *

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 sealsFor(final long blockNumber, final Bytes message) { + if (!attachmentArmedAt(blockNumber) || message == null) { + return List.of(); + } + try { + final Set required = schedule.schemesAt(blockNumber); + final List 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 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 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. / (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 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 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 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 + " 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 schedule() { + return Optional.ofNullable(schedule); + } + + /** Returns the registry, when the hybrid pair is configured. + * + * @return the registry, or empty */ + public Optional 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= + * count= + * .addr=<20-byte hex> mandatory for every index 0..count-1 + * .key.= 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> keys; + private final Map addresses; + + private HybridSignerRegistry( + final long chainId, + final NavigableMap> keys, + final Map 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> keys = new TreeMap<>(); + final Map 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 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 publicKey(final int index, final String schemeId) { + final Map 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 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 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> row : keys.entrySet()) { + writeAll(out, uint32be(row.getKey())); + writeAll(out, addresses.get(row.getKey())); + writeAll(out, uint32be(row.getValue().size())); + for (final Map.Entry 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 schemesOf(final int index) { + final Map 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". + * + *

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. + * + *

Why V2 exists. 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. + * + *

What V2 does instead. 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. + * + *

The two pre-images. + * + * 

+ *   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
+ *
+ * + *

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. + * + *

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. + * + *

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. + * + *

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). + * + *

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. + * + *

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. + * + *

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 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 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 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. + * + *

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 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. + * + *

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]). + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

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 certificate) { + final java.util.Set 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. + * + *

Why this exists. 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. + * + *

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. + * + *

What the exception does NOT relax. 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. + * + *

Producers must not call this. {@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 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 sortedByIndex(final Collection certificate) { + final List 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. + * + *

The gate is on the BLOCK NUMBER. 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. + * + *

Emergency de-arm. 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. + * + *

    + *
  • {@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. + *
  • {@value #PROPERTY_DISABLE} switches both rules off entirely on this node. + *
+ * + *

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. + * + *

AERE OPTIUNI-URGENTA (2026-08-02): both are now COMMAND-LINE OPTIONS. 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. + * + *

AERE CONFIGURATIE-STRICTA (2026-08-06): {@link #fromSystemConfiguration()} is FAIL-CLOSED on + * PRESENCE. 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. + * + *

The gate is on PRESENCE, not on value, and that is what keeps the compatibility property + * intact: + * + *

    + *
  • No {@code aere.pq.*} name set at all - 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. + *
  • At least one name present, 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. + *
+ * + *

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. + * + *

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. + * + *

HONEST LIMITATION, stated in code because it is the same defect class as A8. 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 + * + * 

fork depth <= anchor interval
+ * + * and it is a knob, not an accident. + * + *

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. + * + *

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. + * + *

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 minSealsSchedule; + private final OptionalInt minSealsCeiling; + private final boolean disabled; + private final OptionalInt maxSealsCarried; + private final OptionalInt anchorInterval; + private final long anchorV2Block; + private final NavigableMap 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 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 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 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 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 minSealsSchedule, + final OptionalInt minSealsCeiling, + final boolean disabled, + final OptionalInt maxSealsCarried, + final OptionalInt anchorInterval, + final long anchorV2Block, + final NavigableMap 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 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 schedule = new TreeMap<>(); + for (final Map.Entry 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. + * + *

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 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. + * + *

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 :0} reaches the same end state and went through unseen. + * + *

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 :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. + * + *

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. + * + *

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 readAnchorIntervalSchedule() { + final Read sc = read(PROPERTY_ANCHOR_INTERVAL_SCHEDULE, ENV_ANCHOR_INTERVAL_SCHEDULE); + final NavigableMap 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 readSchedule( + final Read seals, final long anchorBlock) { + final NavigableMap 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. + * + *

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 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. + * + *

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. + * + *

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 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 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 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? + * + *

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? + * + *

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. + * + *

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. + * + *

{@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 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. + * + *

WHAT HAPPENED. 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: + * + *

    + *
  1. The rules off entirely. 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. + *
  2. The rules on, the threshold lowered. 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. + *
+ * + *

WHY THE EXCEPTION BELONGS AT VALIDATION AND NOWHERE ELSE. 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. + * + *

THE BOUNDS, MEASURED, NOT SEARCHED. 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. + * + *

WHAT THE RANGES DO NOT RELAX, AT ANY HEIGHT. 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. + * + *

THE BOUNDS ARE FIXED IN CODE ON PURPOSE. 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. + * + *

THE TYPE IS A LIST BECAUSE A THIRD RANGE MUST NOT REQUIRE TOUCHING A RULE. 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. + * + *

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 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 windows() { + return WINDOWS; + } + + /** + * Whether the anchor rules were out of force ENTIRELY at this height. + * + *

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. + * + *

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. + * + *

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 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 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. + * + *

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. + * + *

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>=9 before K is raised to + * quorum, because at N=7, f=2 the margin is exactly zero. + * + *

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. + * + *

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. + * + *

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. + * + *

The hole this closes, read in the source and not assumed. 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. + * + *

Why refusal and not coverage. 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. + * + *

Fail closed on the unknown. 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. + * + *

Inert when the anchor is not configured. 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. + * + *

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. + * + *

The hole this closes, measured before it was written. 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. + * + *

THE BOUND, AND WHERE THE ARITHMETIC COMES FROM. The refusal is {@code K >= quorum(N)}, + * i.e. the highest value that may be configured is {@code quorum(N) - 1}. + * + *

    + *
  • {@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 4. + *
  • {@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. + *
  • {@code K > N - f} is the WRONG bound and this guard deliberately does not use it. 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. + *
+ * + *

What is a refusal and what is only a shout. 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. + * + *

The verdict is computed from the SAME code path enforcement reads. 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. + * + *

Fail closed on the unknown. A validator-set size of zero or less aborts. "I could not + * count the validators" is not "the threshold is probably fine". + * + *

Inert when the anchor is not armed. 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. + * + *

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. + * + *

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. + * + *

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 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 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 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 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 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 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 seals, final byte wireId) { + return (int) + seals.stream() + .filter(s -> s.getSchemeWireId() == wireId) + .mapToInt(SchemeSeal::getValidatorIndex) + .distinct() + .count(); + } + + private static void requireCanonical(final List 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. + * + *

The defect, measured on the real code path on 2026-08-06

+ * + *

{@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. + * + *

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: + * + *

    + *
  • T3: rebinding one row's address credits a seal made by validator 0's key to validator 1. + *
  • 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. + *
  • T6A: SWAPPING two rows' public keys - no duplicate key, no duplicate address - is accepted. + *
  • T6B: SWAPPING two rows' addresses - again no duplicate of anything - is accepted, and every + * seal is then attributed to the wrong validator. + *
+ * + *

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. + * + *

What a row must now carry

+ * + *

Two proofs over ONE canonical pre-image, because one signature closes only half the defect: + * + *

    + *
  • 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. + *
  • 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. + *
+ * + *

The canonical pre-image

+ * + * 
+ *   "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
+ *
+ * + *

Every field earns its place against a specific, named attack: + * + *

    + *
  • 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. + *
  • publicKey IS IN THE SIGNED MESSAGE. Falcon is not Dilithium here: Cremers, Duzlu, Fiedler, + * Fischlin and Janson (IEEE S&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. + *
  • 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. + *
  • 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. + *
  • count, so a registry cannot be truncated and have its surviving proofs stay valid. + *
+ * + *

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. + * + *

Where this runs, and where it deliberately does not

+ * + *

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. + * + *

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. + * + *

What this does NOT defend against, stated plainly

+ * + *
    + *
  • 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. + *
  • 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. + *
  • 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. + *
  • NOT anything about how a private key is stored or whether it was ever copied. + *
+ */ +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. + * + *

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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

WHAT THIS CLASS DOES NOT DO, stated plainly so nobody relies on absent protection: + * + *

    + *
  • 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. + *
  • 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. + *
  • It says nothing about whether any validator actually holds the private key matching its + * registered public key. + *
+ */ +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}. + * + *

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. + * + *

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 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 entries, + final boolean addressBound) { + this(kind, sourcePath, entries, addressBound, false, -1L, -1L); + } + + Registry( + final SourceKind kind, + final String sourcePath, + final List 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 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. + * + * 

+   *   "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
+   *
+ * + *

Three properties this buys, and each one is the answer to a specific way the older + * concatenation form could be argued with: + * + *

    + *
  • 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. + *
  • 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. + *
  • 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. + *
+ * + * @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. + * + * 
+   *   "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
+   *
+ * + *

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. + * + *

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. + * + *

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. + * + *

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)}. + * + *

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=}, and + * optionally {@code i.addr=<20-byte hex>} to make it address-bound. + * + *

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='."); + } + 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 pks = new TreeMap<>(); + final TreeMap addrs = new TreeMap<>(); + final TreeMap pops = new TreeMap<>(); + final TreeMap 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": "", ...}}. + * + * @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 strays = new ArrayList<>(); + final java.util.Iterator 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 pks = new TreeMap<>(); + final TreeMap addrs = new TreeMap<>(); + final TreeMap pops = new TreeMap<>(); + final TreeMap 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 pks, + final java.util.NavigableMap addrs, + final java.util.NavigableMap pops, + final java.util.NavigableMap 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 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 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 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 entries; // strictly increasing block + private final String source; + + Schedule(final List 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 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. + * + *

Two accepted shapes: + * + * 

+   *   "pqRegistryHash": "0x<64 hex>"                       -- bound from block 0
+   *   "pqRegistryHash": [ {"block": H,  "hash": "0x.."},
+   *                       {"block": H2, "hash": "0x.."} ]   -- height-bound, with rotation
+   *
+ * + *

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 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. + * + *

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 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 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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 loaded; + private final List entryBlocks; // ascending, one per COVERED schedule entry + private final List entryRegistries; // parallel to entryBlocks + private final List uncovered; // schedule entry blocks with no matching registry + private final List misbound; // D-B: hash matched, signed height did not + + RegistrySet( + final List loaded, + final List entryBlocks, + final List entryRegistries, + final List uncovered) { + this(loaded, entryBlocks, entryRegistries, uncovered, List.of()); + } + + RegistrySet( + final List loaded, + final List entryBlocks, + final List entryRegistries, + final List uncovered, + final List 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 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() { + return List.copyOf(misbound); + } + + /** + * The scheduled heights this node CAN answer for. + * + * @return an unmodifiable ascending list + */ + public List 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 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. + * + *

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 registries, final long chainId) { + final List held = new ArrayList<>(); + for (final Registry r : registries) { + if (r != null) { + held.add(r); + } + } + final List blocks = new ArrayList<>(); + final List mapped = new ArrayList<>(); + final List uncovered = new ArrayList<>(); + final List 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 paths, final long chainId) { + final List 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 parseRegistryPaths(final String raw) { + final List 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. + * + *

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 registryAt( + final Schedule schedule, final RegistrySet set, final long blockNumber) { + final Optional 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. + * + *

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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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 " + + "org.hyperledger.besu.consensus.common.bft.tools.PqRegistryHashTool " + + " --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 " + + "org.hyperledger.besu.consensus.common.bft.tools.PqRegistryHashTool " + + " --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 '.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. + * + *

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. + * + *

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: + * + * 

+ *   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
+ *
+ * + *

THREE VERBS. + * + *

    + *
  • {@code hash} prints the canonical hash of every registry file named. This is the value + * that goes into genesis. + *
  • {@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. + *
  • {@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. + *
+ * + *

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 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 o, final long chainId) { + final List files = files(o, "registry"); + if (files.isEmpty()) { + System.out.println("NOT MEASURED: --registry [,...] 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 o, final long chainId) { + final String armingHeightRaw = o.get("arming-height"); + if (armingHeightRaw == null) { + System.out.println("NOT MEASURED: --arming-height 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 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 =. + final Map 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 =, got: " + rot); + return 2; + } + epoci.put(Long.parseLong(rot.substring(0, eq).trim()), Path.of(rot.substring(eq + 1).trim())); + } + + final List 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 --history "); + return 0; + } + + // --------------------------------------------------------------------------------------------- + + private static int verify(final Map o, final long chainId) { + final String genesisRaw = o.get("genesis"); + if (genesisRaw == null) { + System.out.println("NOT MEASURED: --genesis 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 history = files(o, "history"); + final List 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 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 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 files(final Map o, final String key) { + final List out = new ArrayList<>(); + for (final String s : list(o.get(key))) { + out.add(Path.of(s)); + } + return out; + } + + private static List list(final String raw) { + final List 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 optiuni(final String[] args) { + final Map 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 [,...]"); + System.out.println(" generate --chain-id 2800 --arming-height --registry "); + System.out.println(" [--rotation

= ...]"); + System.out.println(" verify --chain-id 2800 --genesis --history [,...]"); + System.out.println(" [--arming-height ] [--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 schemeIds) {} + + private final List steps; + + private PqSchemeSchedule(final List 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 steps = new ArrayList<>(); + long lastHeight = -1; + for (final String piesa : Splitter.on(',').split(raw)) { + final List 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 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 schemesAt(final long height) { + Set inForce = Set.of(); + for (final Step s : steps) { + if (s.fromBlock() <= height) { + inForce = s.schemeIds(); + } else { + break; + } + } + return inForce; + } + + /** All steps, ascending. */ + public List 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 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. + * + *

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. + * + *

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. + * + *

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>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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

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 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 seals) { + final List 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 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 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 extrasFor( + final long blockNumber, final Hash onchainBlockHash) { + final Entry entry = byHash.get(onchainBlockHash); + if (entry == null || entry.blockNumber != blockNumber) { + return List.of(); + } + final List out = new ArrayList<>(entry.extras.values()); + out.sort(PqAnchorV2.CANONICAL); + return out; + } + + public synchronized List 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> it = byHash.entrySet().iterator(); + while (it.hasNext()) { + final Map.Entry e = it.next(); + if (highestSeen - e.getValue().blockNumber > HEIGHT_WINDOW) { + it.remove(); + } + } + while (byHash.size() > MAX_ENTRIES) { + final Iterator oldest = byHash.keySet().iterator(); + oldest.next(); + oldest.remove(); + } + } + + private static final class Entry { + private final long blockNumber; + private final Map seals = new LinkedHashMap<>(); + /** AERE ANCHOR V2: heard extra (non-Falcon) scheme seals, keyed (index << 8 | wire). */ + private final Map 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. + * + *

THE SECOND HALF OF A MEASURED CHAIN DEATH. With the anchor armed at K>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. + * + *

WHY THIS IS NOT DEFECT A8 IN ANOTHER COAT, and the distinction is the whole safety + * argument. 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. + * + *

WHAT THE FILE IS BOUND TO. 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. + * + *

FAILURE IS NEVER FATAL. 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. + * + *

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 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. + * + *

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. + * + *

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 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 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 verified = new ArrayList<>(); + final Set 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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()}. + * + *

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. + * + *

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. + * + *

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 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 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. + * + *

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 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 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 ALL = List.of(FALCON_512, SLH_DSA_128S); + + private SealSchemes() {} + + /** All schemes this build understands, in wire-tag order. */ + public static List 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 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 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 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 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 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 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 { * @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. + * + *

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 voteProviderAfterBlock = @@ -177,7 +200,7 @@ public class BftBlockCreatorFactory { 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. + * + *

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. + * + *

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. + * + *

WHAT IS SELECTED, in order, and each step is the mirror of a validator-side rule: + * + *

    + *
  1. every seal heard for the parent, sorted by validator index (rule: strictly increasing); + *
  2. dropped unless the index maps, through the address-bound Falcon registry, to an address in + * the validator set FOR THE PARENT (rule: eligible signer); + *
  3. dropped unless the Falcon signature verifies over M(parent) (rule: k verifications); + *
  4. refused entirely if fewer than K(N) survive (rule: k >= K). + *
+ * + *

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. + * + *

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. + * + *

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. + * + *

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 . 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. + * + *

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 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. + * + *

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 heard = + PqSealCache.instance().sealsFor(parentNumber, parentHeader.getHash()); + + final PqSignerRegistry registry = PqSignerRegistry.falconSealSupport(); + final Set

eligible = validatorsForParent(parentHeader, protocolContext); + + final List certificate = new ArrayList<>(); + final Set
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 falconCertificate, + final Bytes32 message, + final int required, + final int sealCap) { + final long parentNumber = parentHeader.getNumber(); + final List v2 = new ArrayList<>(); + final Set 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 schemes = + hybrid.schedule().map(sch -> sch.schemesAt(parentNumber)).orElse(Set.of()); + final List heard = + PqSealCache.instance().extrasFor(parentNumber, parentHeader.getHash()); + for (final String schemeId : schemes) { + if (SealSchemes.FALCON_512.id().equals(schemeId)) { + continue; + } + final Optional 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 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 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. + * + *

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

validatorsForParent( + final BlockHeader parentHeader, final ProtocolContext protocolContext) { + final Collection
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 stack = new LinkedList(); + 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 stack = new LinkedList(); + 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. + *

+ * 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. + *

+ */ +@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}. + * + *

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. + * + * 

+ *   java -cp <besu lib> org.hyperledger.besu.consensus.common.bft.tools.PqRegistryHashTool \
+ *        <registry-file> [--chain-id N] [--block H] [--quiet]
+ *
+ * + *

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 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 [--chain-id N] [--block H] [--quiet]\n" + + " 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, 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. + * + *

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. + * + *

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 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 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 props = new HashMap<>(); + final Map 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 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. + 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 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. + * + *

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 properties = new HashMap<>(); + private final Map environment = new HashMap<>(); + private final List 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 schedule() { + final Map 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. + * + *

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. + * + *

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 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. + * + *

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 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 ":0" reaches the same state, and it used to pass. + * + * And it is not theoretical: PLAN-ACTIVARE recommends ":0,: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 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. + * + *

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. + * + *

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. + * + *

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 privateKeys = new ArrayList<>(); + private final List

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 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
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 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 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 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 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 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 subsetA = Arrays.asList(seal(0), seal(1), seal(2), seal(3)); + final List 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 ordered = Arrays.asList(seal(0), seal(1)); + final List 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 original = List.of(new FalconSeal(3, signatureFor(3, 0))); + final List 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 real1 = Arrays.asList(seal(2), seal(6), seal(1)); + final List 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 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 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 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 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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

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 falconKeys = new ArrayList<>(); + private final List slhKeys = new ArrayList<>(); + private final List

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 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 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 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 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 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 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
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 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 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 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 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 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 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 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 cert = + List.of( + new SchemeSeal(FALCON, 0, Bytes.wrap(sigFalcon)), + new SchemeSeal(SLHDSA, 0, Bytes.wrap(sigSlh))); + final List 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 privateKeys = new ArrayList<>(); + private final List

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 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 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 entries) + throws Exception { + final List 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. + * + *

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>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)". + * + *

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>0 it never does. + * + *

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. + * + *

    + *
  1. {@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. + *
  2. {@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. + *
  3. {@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. + *
  4. {@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. + *
  5. {@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. + *
+ * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

WHAT EACH TEST MEASURES, and how each can fail: + * + *

    + *
  1. {@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. + *
  2. {@link #aMalformedForkBlockRefusesToStart()} and {@link #aNegativeForkBlockRefusesToStart()} + * - the config-time half of the finding, at construction. + *
  3. {@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. + *
  4. {@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. + *
  5. {@link #anAttachHeightBeforeTheObservationHeightRefuses()} and {@link + * #aForkHeightAtTheObservationHeightRefuses()} - half two on its own stimulus: the ordering + * is wrong and the node starts anyway. + *
  6. {@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. + *
  7. {@link #aGenesisAnchoredRegistryNeedsNoObservationHeight()} and {@link + * #anObservationHeightWithoutBlockingIsHarmless()} - the scope controls. A guard that refused + * every blocking configuration would pass every test above and be useless. + *
+ * + *

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? + * + *

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}: + * + *

+ * + * "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". + * + *
+ * + *

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. + * + *

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: + * + * 

+ *   N=7,  keyed 7, quorum 5 -> 5 guaranteed    K=5 reachable, margin exactly 0
+ *   N=9,  keyed 7, quorum 6 -> 4 guaranteed    K=5 NOT guaranteed
+ *
+ * + *

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. + * + *

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. + * + *

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. + * + *

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". + * + *

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. + * + *

WHAT EACH TEST MEASURES, and why each of them can fail: + * + *

    + *
  1. {@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. + *
  2. {@link #addingOneValidatorMustNotTurnSealAttachmentOff()} - D-078 itself, on the exact + * stimulus in the title: one more validator in the set, with no Falcon key. + *
  3. {@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. + *
  4. {@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. + *
+ * + *

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

keyedValidators = new ArrayList<>(); + private final List 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 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
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 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. + * + *

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: + * + * 

+   *   N=7, keyed 7, quorum 5 -> 5 guaranteed   K=5 is met, with EXACTLY zero margin
+   *   N=8, keyed 7, quorum 6 -> 5 guaranteed   K=5 is still met, still zero margin
+   *   N=9, keyed 7, quorum 6 -> 4 guaranteed   K=5 is NOT guaranteed any more
+   *
+ * + *

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

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

{@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 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 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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

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

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 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}. + * + *

{@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 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 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 bound; + + private void bind(final List 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 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 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. + * + *

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). + * + *

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. + * + *

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 privateKeys = new ArrayList<>(); + private final List

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 entries) + throws Exception { + final List 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. + * + *

WHAT WAS MEASURED BEFORE THIS TEST EXISTED, on the real verification path, with the startup + * gate reporting MATCH and the header ACCEPTED every time: + * + *

    + *
  • T3, one row's address repointed: a seal made by validator 0's key credited to validator 1. + *
  • T4, one key at two indices: two seals from a SINGLE private key satisfy a threshold of 2. + *
  • 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. + *
  • T6B, two rows' addresses swapped: accepted, again with nothing duplicated, and every seal + * attributed to the wrong validator. + *
+ * + *

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. + * + *

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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 rows() { + return rows(CHAIN_ID); + } + + private static List rows(final long chainId) { + final List 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 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 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 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. + * + *

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. + * + *

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. + * + *

WHAT THIS FILE ASSERTS, as a property and not as a scenario: at and above the arming height, + * a node that cannot say which key set was in force must REFUSE, not guess. 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. + * + *

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 privateKeys = new ArrayList<>(); + private final List

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 entries) + throws Exception { + final List 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

{@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? + * + *

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 enforcedHeights() { + final List 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 availableConfigurations( + final PqRegistryHash.Schedule schedule, + final PqRegistryHash.Registry before, + final PqRegistryHash.Registry after) { + final List 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 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 heights = enforcedHeights(); + final List configurations = + availableConfigurations(schedule, before, after); + + final List report = new ArrayList<>(); + NodeConfiguration complete = null; + for (final NodeConfiguration c : configurations) { + final List 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 report = new ArrayList<>(); + for (final NodeConfiguration c : availableConfigurations(schedule, withCompromised, revoked)) { + boolean all = true; + final List 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 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 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 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 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. + * + *

MEASURED ON A NETWORK FIRST, NOT ASSUMED. With the anchor armed at K>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. + * + *

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. + * + *

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: + * + *

    + *
  1. {@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. + *
  2. {@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. + *
  3. {@link #aCorruptFileDoesNotStopTheNode()} - truncated, random, empty, a directory where the + * file should be. Every one of them yields an empty cache and no exception. + *
  4. {@link #aFileFromAnotherHeightOrAnotherChainIsIgnored()} - the binding checks, before a + * single signature is verified. + *
  5. {@link #theWriteIsAtomicUnderAConcurrentReader()} - a reader hammering the file across 120 + * writes never observes a partial file. + *
  6. {@link #thePathComesFromTheDataDirectory()} - the path is derived, never configured. + *
  7. {@link #whatOneWriteCostsAgainstTheBlockInterval()} - the price of doing this on the + * consensus thread, as a number rather than as a hope. + *
+ * + *

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

validators = new ArrayList<>(); + private final List 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. + * + *

Three shapes of forgery are in the one file, because "a forged seal" is not one thing: + * + *

    + *
  1. 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. + *
  2. index 4, random bytes of exactly the right length. The cheapest forgery there is. + *
  3. 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. + *
+ */ + @Test + public void aForgedSealInTheFileIsRejectedAtReadAndNeverEntersTheCache() throws Exception { + final List 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 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 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 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 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 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 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 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 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
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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

THE RULE CHOSEN, and why it is the correct one rather than merely a working one: + * + *

    + *
  • 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. + *
  • 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()}. + *
  • 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()}. + *
  • 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()}. + *
  • An entry no held file reproduces stays UNCOVERED, which is a different condition with a + * different message. It is not compared - {@link #anUncoveredEntryIsNotAMisboundOne()}. + *
+ * + *

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. + * + *

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 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 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 entries) throws IOException { + final List 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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 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 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 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 entries) throws IOException { + final List 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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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 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 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 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). + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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. + * + *

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 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. + * + *

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 { 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 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. + * + *

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 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, final List> roundChanges, final List> prepares) { + multicastProposal(roundIdentifier, block, blockAccessList, roundChanges, prepares, + Optional.empty()); + } + + /** + * Multicast proposal carrying the proposer's optional post-quantum seal (AERE PQ, 2026-08-30). + * + *

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, + final List> roundChanges, + final List> prepares, + final Optional 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. + * + *

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) { 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) { + 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, + final java.util.List 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. + * + *

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. + * + *

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; + // 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 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) { + this(roundIdentifier, digest, commitSeal, falconSeal, List.of()); + } + + /** + * Instantiates a new Commit payload carrying a HYBRID post-quantum certificate. + * + *

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: + * + *

    + *
  • 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; + *
  • 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; + *
  • a signature has exactly ONE home, so the two slots can never disagree about Falcon. + *
+ * + *

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. + * + *

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, + final List 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. * + *

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. + * + *

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. + * + *

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. + * + *

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 = 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 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 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 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). + * + *

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, + final List> roundChanges, + final List> prepares, + final Optional 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. + * + *

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) { + 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) { + 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, + final java.util.List 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 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 preparedRoundData, + final Optional 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. + * + *

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 byte for byte as upstream, + * and that is precisely the property that lets the binary be rolled onto a live fleet without a + * flag day. + * + *

NOTHING EMITS SUCH A PREPARE YET. 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. + * + *

What the seal signs is NOT this file's business, 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; /** - * 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) { this.roundIdentifier = roundIdentifier; this.digest = digest; + this.falconSeal = falconSeal == null ? Optional.empty() : falconSeal; } /** * Read from rlp input and return prepare payload. * + *

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 = 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 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. + * + *

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 byte for byte as + * upstream, which is the property that lets the binary be rolled onto a live fleet without a + * flag day. + * + *

NOTHING EMITS SUCH A PROPOSAL YET. 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. + * + *

What the seal signs is NOT this file's business: 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. + * + *

Why the trailing element is parsed strictly: 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; + private final Optional 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) { + final Optional blockAccessList, + final Optional 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) { + 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 = 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 = 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 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. + * + *

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 byte for byte as + * upstream, which is the property that lets the binary be rolled onto a live fleet without a + * flag day. + * + *

NOTHING EMITS SUCH A ROUND-CHANGE YET. 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. + * + *

What the seal signs is NOT this file's business: 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. + * + *

Why the trailing element is parsed strictly: 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; + private final Optional 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) { + final Optional preparedRoundMetadata, + final Optional 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) { + 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 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 = 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 = 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 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 roundChangeSealFor( + final ConsensusRoundIdentifier roundIdentifier, + final Optional 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. + * + *

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. + * + *

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 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 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; 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> 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 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 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 = 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. + * + *

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 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. + * + *

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 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 = falconSealFor(block, commitHash); + // AERE HYBRID: the other schemes' extras, over the SAME message; empty on any node today. + final java.util.List 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 = falconSealFor(block, commitHash); + // AERE HIBRID: aceleasi extrase si pe drumul tarziu, ca cele doua locuri sa nu divearga. + final java.util.List 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 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. + * + *

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. + * + *

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 extras = + msg.getExtraSeals(); + if (!extras.isEmpty()) { + PqSealCache.instance().recordExtras(height, msg.getDigest(), extras); + } + } + + private void pqCacheHeardSeals(final QbftBlock block) { + final Collection 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 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 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 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 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 getExtraSeals() { + return commitMessages.values().stream() + .flatMap(cp -> cp.getSignedPayload().getPayload().getExtraSeals().stream()) + .collect(Collectors.toList()); + } + + public Collection 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 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 commitSeals, + final Collection falconSeals) { + return createSealedBlock(block, roundNumber, commitSeals); + } + + /** + * Convenience empty Falcon seal collection. + * + * @return an empty collection of Falcon seals + */ + static Collection 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. + * + *

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

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. + * + *

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

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
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 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. + * + *

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. + * + *

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. + * + *

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 refusal( + final long height, + final Address author, + final Hash commitDigest, + final Optional 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 refusal( + final long height, + final Address author, + final Hash commitDigest, + final Optional seal, + final List extraSeals) { + final Optional 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 hybridRefusal( + final long height, + final Address author, + final Hash commitDigest, + final FalconSeal falconSeal, + final List extraSeals) { + final Set 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 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 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 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 falconRefusal( + final long height, + final Address author, + final Hash commitDigest, + final Optional 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. + * + *

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. + * + *

WHY THIS IS A DIFFERENT LAYER FROM COMMIT, AND MORE DANGEROUS. 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. + * + *

WHAT THE SEAL SIGNS, AND WHY NOT THE SAME THING AS COMMIT. 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. + * + *

DISARMED BY DEFAULT. 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. + * + *

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 refusal( + final long height, + final int round, + final Address author, + final Hash digest, + final Optional 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). + * + *

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. + * + *

WHAT THIS LAYER BUYS, said precisely. 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. + * + *

WHAT THE SEAL SIGNS. 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. + * + *

DISARMED BY DEFAULT. 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. + * + *

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 refusal( + final long height, + final int round, + final Address author, + final Hash digest, + final Optional 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). + * + *

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. + * + *

WHAT THIS LAYER BUYS, said precisely. 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. + * + *

WHAT THE SEAL SIGNS. 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. + * + *

DISARMED BY DEFAULT. 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. + * + *

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 refusal( + final long height, + final int targetRound, + final Address author, + final Optional preparedRoundMetadata, + final Optional 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. + * + *

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

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
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
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 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. + * + *

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. + * + *

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 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) + * + *

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. + * + *

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

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
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
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 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. + * + *

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 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 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. + * + *

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 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 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. + * + *

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. + * + *

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). + * + *

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. + * + *

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). + * + *

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. + * + *

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. + * + *

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 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 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 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. + * + *

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). + * + *

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 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. + * + *

What this proves, with real Falcon-512 signatures and nothing mocked on the cryptographic path: + * + *

    + *
  • anchor armed: a seal made exactly as the emitter makes it (over {@code + * PqAnchorProducer.commitSealMessage}) COUNTS through the production message; + *
  • 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; + *
  • anchor armed, an emitter that kept signing the digest is REFUZAT by the fixed verifier; + *
  • anchor never armed: the message IS the commit digest, so old and new verifiers agree. + *
+ */ +@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 bindings = new HashMap<>(); + private final Map cheiPublice = new HashMap<>(); + private final Map 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 bindings = new HashMap<>(); + private final Map cheiPublice = new HashMap<>(); + private final Map 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 bindings; + final Map keys; + + RegistruDeTest(final Map bindings, final Map 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 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 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 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 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 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 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 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 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 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 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 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. + * + *

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. + * + *

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. + * + *

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 bindings; + private final Map keys; + + RegistryPerScheme( + final SealScheme scheme, final Map bindings, final Map 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 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. + * + *

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 where exactly the nail is: in the enforcement class, or only + * in the wiring? + * + *

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 without touching one line of consensus + * code. 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. + * + *

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. + * + *

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 bindings; + private final Map keys; + + RegistryPerScheme( + final SealScheme scheme, final Map bindings, final Map 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 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 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. + * + *

What is proven here, each item closing one way of being wrong: + * + *

    + *
  1. below the arming height NOTHING changes - the condition for the binary to sit on the fleet; + *
  2. above it, a PREPARE without a seal does NOT count; + *
  3. a seal from ANOTHER validator does not vouch for this author; + *
  4. 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; + *
  5. a seal from a DIFFERENT ROUND does not pass; + *
  6. a mistyped configuration REFUSES, it does not disarm. + *
+ * + *

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 bindings; + final Map keys; + + RegistruDeTest(final Map bindings, final Map 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 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 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 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 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 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. + * + *

    + *
  1. below the arming height NOTHING changes - the condition for the binary to sit on the fleet; + *
  2. above it, a PROPOSAL without a seal is refused; + *
  3. a seal from ANOTHER validator does not vouch for this proposer; + *
  4. 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; + *
  5. a seal from a DIFFERENT ROUND does not pass; + *
  6. an index the registry binds to nobody does not pass; + *
  7. a mistyped configuration REFUSES, it does not disarm; + *
  8. the enforcement gate and the emission gate are two different switches. + *
+ * + *

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 bindings; + final Map keys; + + TestRegistry(final Map bindings, final Map 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 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 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 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 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 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 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. + * + *

    + *
  1. below the arming height NOTHING changes - the condition for the binary to sit on the fleet; + *
  2. above it, a ROUND-CHANGE without a seal is refused; + *
  3. a seal from ANOTHER validator does not vouch for this author; + *
  4. 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; + *
  5. a seal from a DIFFERENT TARGET ROUND does not pass; + *
  6. a seal from a BARE round-change does not pass on one claiming a prepared block, and vice + * versa; + *
  7. an index the registry binds to nobody does not pass; + *
  8. a mistyped configuration REFUSES, it does not disarm; + *
  9. the enforcement gate and the emission gate are two different switches. + *
+ * + *

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 bindings; + final Map keys; + + TestRegistry(final Map bindings, final Map 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 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 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 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 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 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 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 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 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 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 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 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. + * + *

WHY THIS TEST IS THE ONE THAT MATTERS. 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. + * + *

The question this test answers, by measurement rather than by argument: with the + * post-quantum enforcement armed, does that adversary gain anything at all? 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. + * + *

THE CONTROLS, without which the refusals would prove nothing: + * + *

    + *
  1. 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. + *
  2. 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. + *
  3. 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. + *
+ * + *

TWO OF THOSE CONTROLS EXIST BECAUSE THE NEGATIVE CONTROL CAUGHT THEIR ABSENCE + * (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. + * + *

WHAT THIS DOES NOT PROVE, said plainly: 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 bindings = Map.of(0, VICTIM, 1, OTHER); + private final Map 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 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 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 refusal = + commitArmed().refusal(H, VICTIM, COMMIT_DIGEST, Optional.empty()); + assertThat(refusal).isPresent(); + } + + @Test + void aStolenECDSAKeyBuysNORoundChange() { + final Optional 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? + * + *

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". + * + *

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? + * + *

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. + * + *

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: + * + *

    + *
  1. 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; + *
  2. the coupling already exists: {@code RoundChangeMessageValidator} builds a + * {@link PrepareValidator} with the three-argument constructor, and that one wires its own + * enforcement from the system configuration. + *
+ * + *

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. + * + *

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> 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? + * + *

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) { + return blockHeaderValidator( + minimumTimeBetweenBlocks, + useValidatorContract, + baseFeeMarket, + PqAnchorConfig.fromSystemConfiguration()); + } + + /** + * Produces a BlockHeaderValidator configured for assessing bft block headers, with an explicit V2 + * certificate-anchor configuration. + * + *

AERE ANCORA-V2 (2026-08-01). Two rules are added and one is retired, all indexed on the BLOCK + * NUMBER: + * + *

    + *
  • {@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. + *
  • {@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). + *
  • {@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. + *
+ * + *

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. + * + *

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, + 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. + * + *

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 voteToValue = @@ -102,9 +120,91 @@ public class QbftExtraDataCodec extends BftExtraDataCodec { final List 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 falconSeals; + final List 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 commitSeals) { + return createSealedBlock(block, roundNumber, commitSeals, Collections.emptyList()); + } + + @Override + public QbftBlock createSealedBlock( + final QbftBlock block, + final int roundNumber, + final Collection commitSeals, + final Collection 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

registered = pqc.registeredValidatorAddresses(); + final Set
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 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 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 verifiedDistinctSeals( + final FalconSealSupport pqc, + final long blockNumber, + final Hash commitHash, + final Collection seals, + final Set
eligible, + final OptionalInt cap) { + final List out = new ArrayList<>(); + final Set
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 BftBlockCreatorFactoryBoth 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}. + * + *

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 (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) { + 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. + * + *

RETIRED ON CHAIN 2800, AND EVERYTHING BELOW DESCRIBES A RULE THAT NO LONGER APPLIES THERE + * (finding D-235, corrected 2026-08-19). 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. + * + *

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. + * + *

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. + * + *

AERE audit fix (AUD-CONSENSUS-1 / AUD-CONSENSUS-2, 2026-07-18). Both the Falcon quorum + * threshold AND the counted-seal set are now bound to ONE well-defined set: + * + * 

+ *   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
+ *
+ * + *

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). + * + *

ECDSA stays decisive. 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. + * + *

Behaviour is fork-gated by {@code aere.falcon.forkBlock} / {@code AERE_FALCON_FORKBLOCK}: + * + *

    + *
  • 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. + *
  • 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. + *
+ * + *

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. + * + *

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. + * + *

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 2295 lines in twenty minutes, about 165.000 + * a day per node, 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. + * + *

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. + * + *

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. + * + *

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. + * + *

{@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. + * + *

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. + * + *

Two reasons to log at INFO, and no others: + * + *

    + *
  • the outcome CHANGED since the last INFO, so an operator sees every transition on the block + * it happens + *
  • {@link #LOG_HEARTBEAT_BLOCKS} have passed, so the line never vanishes from a quiet log + *
+ * + *

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 falconSeals = extraData.getFalconSeals(); + + final BftContext bftContext = protocolContext.getConsensusContext(BftContext.class); + final Collection

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
registered = pqc.registeredValidatorAddresses(); + final Set
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
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 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. + * + *

Why a second copy of a rule that already exists. {@link PqAnchorDigestRule} is DETACHED. + * Besu decides which rules run from the {@code HeaderValidationMode}, and the two facts that matter + * were measured, not assumed: + * + *

    + *
  • {@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. + *
  • {@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. + *
+ * + *

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. + * + *

It is the same verdict, not a second opinion. 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. + * + *

Deliberately NOT in light validation. {@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. + * + *

Inactive below H. 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. + * + *

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. + * + *

Pure function of the header. 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. + * + *

WHERE IT ACTUALLY RUNS. MEASURED 2026-08-02, and this paragraph CORRECTS an earlier claim in + * this same file. 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: + * + *

    + *
  • {@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}.] + *
  • 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}.] + *
  • 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.] + *
+ * + *

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.] + * + *

includeInLightValidation, measured. 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. + * + *

Inactive below H. 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. + * + *

Fail-closed above H. 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. + * + *

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 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 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. + * + *

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. + * + *

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 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. + * + *

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. + * + *

    + *
  1. k = |C| is at least K(height), the staged threshold; + *
  2. the validator indices are STRICTLY increasing, so there is one accepted order and a repeated + * index is unrepresentable; + *
  3. every index maps, through the registry, to an address in the PARENT's validator set; + *
  4. every signature verifies as Falcon-512 over M(parent). + *
+ * + *

Why the "what I heard" comparison is absent, and why that is the entire point. 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. + * + *

Not in light validation. 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. + * + *

Inactive below H, checked as the first statement, before any decode. + * + *

Fail-closed above H, on every path including exceptions and including a missing or + * mismatched parent. + * + *

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>=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 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

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
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. + * + *

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

eligible, + final Bytes32 message, + final List certificate) { + final Set
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 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 falcon = new ArrayList<>(); + final Set 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
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
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 requiredSchemes = new HashSet<>(); + hybrid.schedule().ifPresent(sch -> requiredSchemes.addAll(sch.schemesAt(parent.getNumber()))); + requiredSchemes.remove(SealSchemes.FALCON_512.id()); + final Map counted = new HashMap<>(); + for (final SchemeSeal s : seals) { + if (s.getSchemeWireId() == SealSchemes.FALCON_512.wireId()) { + continue; + } + final Optional 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 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 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 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
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. + * + *

The rule this exists to obey. 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. + * + *

Why a header rule. 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. + * + *

It cannot reject anything. {@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. + * + *

It says nothing when nothing is overridden. 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. + * + *

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. + * + *

The hole this closes, stated as the measurement that found it. 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." + * + *

Why a header rule and not a background timer. 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. + * + *

What it does on mismatch, and why refusing is the fail-closed direction. 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. + * + *

Inert unless somebody armed it, three times over. 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. + * + *

DETACHED. And the light-validation flag does NOT keep it off the sync path - that claim + * was here and it was wrong. 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. + * + *

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. + * + *

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 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 rulesInside(final Object validator) throws Exception { + final List 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. + * + *

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 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 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 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 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 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. + * + *

MEASURED ON A LIVE NODE, and that is why this test exists. The rule wrote the summary at INFO + * on every imported block: 2295 lines in twenty minutes, about 165,000 a day per node, 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. + * + *

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 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. + * + *

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. + * + *

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. + * + *

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 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 subsetA = List.of(seal(0), seal(1), seal(2), seal(3), seal(4)); + final List 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 original = List.of(seal(0), seal(1), seal(2)); + final List 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 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 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 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. + * + *

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. + * + *

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 ARRIVAL_ORDER = List.of(2, 6, 1); + + /** A second measured arrival order, from another header of the same range. */ + private static final List 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 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 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 indicesInArrivalOrder) { + final List 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 indices) { + final List 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 sealsFor(final BlockHeader parent, final List 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 seals = new ArrayList<>(); + for (final int index : indices) { + seals.add(new FalconSeal(index, LocalRegistry.sign(index, message))); + } + return seals; + } + + private ProtocolContext contextWith(final Collection

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 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. + * + *

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. + * + *

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 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 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 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

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 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 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 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 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 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 sealsFor(final BlockHeader parent, final List indices) { + final Bytes32 message = PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes()); + final List 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 indices) { + final List 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
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> 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 generations = new TreeMap<>(); + + private FakeRegistry() { + final Map 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 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 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 signers = List.of(0, 1, 2, 3, 4); + for (int position = 0; position < signers.size(); position++) { + final List 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
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 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 certificate) { + final List 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. + * + *

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. + * + *

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 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 certificate(final BlockHeader parent, final int falconCount, final int slhCount) { + final Bytes32 m = PqAnchor.commitMessage(CHAIN_ID, parent.getNumber(), parent.getHash().getBytes()); + final List 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 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 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 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 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 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 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 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 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 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 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

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. + * + *

{@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. + * + *

{@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. + * + *

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

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. + * + *

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. + * + *

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. + * + *

This class measures the WIRING, in both directions, and it is the only thing that separates the + * repair from a claim about it: + * + *

    + *
  • the legacy rule really does stand down at H, so it really cannot be the feed above H; + *
  • {@link PqAnchorSealsRule}, which runs at every height from H, really does feed it. + *
+ */ +// 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
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 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. + * + *

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. + * + *

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. + * + *

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 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 headers) { if (checkpointRange.hasEnd()) {