sgns::PublicChainInputValidator¶
Validator for transactions that reference external public-chain proofs.
#include <PublicChainInputValidator.hpp>
Inherits from sgns::IInputValidator
Public Functions¶
| Name | |
|---|---|
| bool | RegisterForChain(const std::string & chain_id) Attempts to claim chain_id in the global registry and records successful claims for self-removal on destruction. |
| ~PublicChainInputValidator() override | |
| void | SetRpcEndpoints(const std::string & chain_id, std::vector< WeightedRpcEndpoint > endpoints) Configure weighted RPC endpoints for a source chain. |
| void | AddRpcEndpoints(const std::string & chain_id, std::vector< WeightedRpcEndpoint > endpoints) Merge weighted RPC endpoints into a source chain's existing list. |
| virtual bool | ValidateUTXOParameters(const UTXOTxParameters & params, const std::string & address, const UTXOManager & utxo_manager) const override Validates local UTXO structure for externally sourced claims. |
| virtual bool | ValidateWitness(const ConsensusSubject & subject, const std::shared_ptr< GeniusTransaction > & tx, const UTXOTxParameters & params, const std::shared_ptr< Blockchain > & blockchain) const override Validates the external witness data supplied by consensus. |
| virtual bool | RequiresConsensusUTXOData() const override Public-chain validation does not require local UTXO witness data. |
| void | SetTransportFactory(TransportFactory factory) Inject a custom transport factory for DI-based mock support. |
| std::optional< std::string > | GetFirstRpcUrl(const std::string & chain_id) const Returns the first RPC endpoint URL for a given chain ID, if any exist. |
| std::optional< RpcVerificationEvidence > | TakeEvidence(const std::string & claim_key) const Consumes the verification evidence recorded for a claim. |
| std::optional< std::string > | GetFirstConfiguredChainId() const Returns the first configured chain id, if any (Phase 6, D-01). |
| std::optional< std::string > | ClaimKey(const ConsensusSubject & subject) Derives the claim key that binds verification evidence to a subject. |
Friends¶
| Name | |
|---|---|
| class | ::PublicChainInputValidatorTestAccess Friend accessor for unit testing VerifyPublicChainSmartContract and the wired rpc_endpoints_ (mirrors BridgeRelayerTestAccess). |
Additional inherited members¶
Public Types inherited from sgns::IInputValidator
| Name | |
|---|---|
| using const IInputValidator * | ValidatorPtr |
Public Functions inherited from sgns::IInputValidator
| Name | |
|---|---|
| virtual | ~IInputValidator() =default Destroys the input validator. |
| bool | Register(const std::string & chain_id, ValidatorPtr validator) Register a validator for a chain if the chain is currently unowned. |
| void | UnregisterIf(const std::string & chain_id, ValidatorPtr expected) Remove a chain's registration only if it currently points to expected (compare-and-remove). This prevents a non-owner from removing the current registration and lets a validator self-clean on destruction. |
| ValidatorPtr | Get(const std::string & chain_id) |
Public Functions Documentation¶
function RegisterForChain¶
Attempts to claim chain_id in the global registry and records successful claims for self-removal on destruction.
Return: True when this validator claimed the chain; false when another validator is already registered for it.
function ~PublicChainInputValidator¶
function SetRpcEndpoints¶
Configure weighted RPC endpoints for a source chain.
Parameters:
- chain_id Source chain identifier (e.g. "1" for Ethereum).
- endpoints Weighted RPC endpoint URLs for verifying burn receipts.
function AddRpcEndpoints¶
Merge weighted RPC endpoints into a source chain's existing list.
Parameters:
- chain_id Source chain identifier (e.g. "1" for Ethereum).
- endpoints Weighted RPC endpoints to merge (URL-deduped).
Unlike SetRpcEndpoints (wholesale replace), this preserves endpoints already configured for the chain (e.g. operator-supplied private/API-key endpoints from GeniusNode::ConfigureRpcEndpoint) and appends the new ones, deduplicating by URL. Used by the chainlist runtime fetch so an async non-empty fetch never drops higher-weight private endpoints.
function ValidateUTXOParameters¶
virtual bool ValidateUTXOParameters(
const UTXOTxParameters & params,
const std::string & address,
const UTXOManager & utxo_manager
) const override
Validates local UTXO structure for externally sourced claims.
Parameters:
- params UTXO inputs and outputs carried by the transaction.
- address Source address; ignored for public-chain validation.
- utxo_manager Local UTXO manager; ignored for public-chain validation.
Return: True when both input and output lists are non-empty.
Reimplements: sgns::IInputValidator::ValidateUTXOParameters
function ValidateWitness¶
virtual bool ValidateWitness(
const ConsensusSubject & subject,
const std::shared_ptr< GeniusTransaction > & tx,
const UTXOTxParameters & params,
const std::shared_ptr< Blockchain > & blockchain
) const override
Validates the external witness data supplied by consensus.
Parameters:
- subject Consensus subject carrying UTXO commitment data.
- tx Transaction that references the public-chain source event.
- params UTXO inputs and outputs carrying the source reference and minted outputs.
- blockchain Blockchain service; currently unused by public-chain validation.
Return: True when tx is present, params are non-empty, and the source reference verification succeeds.
Reimplements: sgns::IInputValidator::ValidateWitness
function RequiresConsensusUTXOData¶
Public-chain validation does not require local UTXO witness data.
Return: Always false.
Reimplements: sgns::IInputValidator::RequiresConsensusUTXOData
Bridge mints use the EVM transaction hash as input, not a local UTXO. Receipt verification is handled via RPC in VerifyPublicChainSmartContract.
function SetTransportFactory¶
Inject a custom transport factory for DI-based mock support.
Parameters:
- factory Callable taking (url, timeout) → unique_ptr
.
When set, every call to VerifyPublicChainSmartContract() will use this factory to create transport instances instead of the default RpcHttpTransport factory. Not called in production (D-16).
function GetFirstRpcUrl¶
Returns the first RPC endpoint URL for a given chain ID, if any exist.
Parameters:
- chain_id Numeric chain ID as a string (e.g. "1" for Ethereum).
Return: The first endpoint URL if one exists, std::nullopt otherwise.
Used by the startup catch-up scan to obtain an RPC URL for eth_getLogs queries without needing to re-parse the ChainList provider data.
function TakeEvidence¶
Consumes the verification evidence recorded for a claim.
Parameters:
- claim_key Key produced by ClaimKey() for the same subject.
Return: Recorded evidence, or std::nullopt when no evidence exists for the claim.
Evidence is stored by ValidateWitness() once the RPC quorum has run for that exact subject, and is removed by this call so it can back exactly one vote and can never be reused for another claim. Thread-safe.
function GetFirstConfiguredChainId¶
Returns the first configured chain id, if any (Phase 6, D-01).
Return: First configured chain id, or std::nullopt when none configured.
Used by GeniusNode's slot-hash populator lambda to resolve a chain context for single-chain deployments (multi-chain resolution is a future enhancement). Read-only and additive (D-10: Tier 1 untouched).
function ClaimKey¶
Derives the claim key that binds verification evidence to a subject.
Parameters:
- subject Consensus subject carrying the bridge claim.
Return: Canonical claim key, or std::nullopt when the subject cannot be canonicalised.
The key is the canonical subject id (ConsensusManager::ComputeSubjectId), so evidence produced while validating one proposal's subject can never be read back for a different claim (issue #364, "Claim binding").
Friends¶
friend ::PublicChainInputValidatorTestAccess¶
Friend accessor for unit testing VerifyPublicChainSmartContract and the wired rpc_endpoints_ (mirrors BridgeRelayerTestAccess).
Updated on 2026-08-28 at 01:08:42 +0000