Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnexpectedBlockNumber is returned when a block arrives out of order (higher than expected). ErrUnexpectedBlockNumber = &labeledError{ err: errors.New("received unexpected block number"), label: "unexpected_block_number", } // ErrDuplicateBlock is returned when a block that was already processed arrives again. ErrDuplicateBlock = &labeledError{ err: errors.New("received duplicate block"), label: "duplicate_block", } // ErrMalformedBlock is returned when a block structure is invalid. ErrMalformedBlock = &labeledError{ err: errors.New("received malformed block"), label: "malformed_block", } // ErrHeaderHashMismatch is returned when the previous block header hash doesn't match. ErrHeaderHashMismatch = &labeledError{ err: errors.New("previous block header hash mismatch"), label: "header_hash_mismatch", } // ErrDataHashMismatch is returned when the block data hash doesn't match the header. ErrDataHashMismatch = &labeledError{ err: errors.New("block data hash mismatch"), label: "data_hash_mismatch", } // ErrSignatureVerification is returned when block signature verification fails. ErrSignatureVerification = &labeledError{ err: errors.New("block signature verification failed"), label: "signature_verification", } // ErrConfigBlockAhead is returned when config block number is ahead of current block. ErrConfigBlockAhead = &labeledError{ err: errors.New("config block number ahead of current block"), label: "config_block_ahead", } // ErrLastConfigIndexMismatch is returned when block's last config index doesn't match expected. ErrLastConfigIndexMismatch = &labeledError{ err: errors.New("last config block index mismatch"), label: "last_config_index_mismatch", } // ErrConfigBlockSelfReference is returned when config block doesn't reference itself. ErrConfigBlockSelfReference = &labeledError{ err: errors.New("config block self-reference mismatch"), label: "config_block_self_reference", } // ErrGenesisBlockMismatch is returned when delivered genesis block doesn't match known genesis. ErrGenesisBlockMismatch = &labeledError{ err: errors.New("delivered genesis block mismatch"), label: "genesis_block_mismatch", } // ErrLastConfigIndexFetch is returned when fetching last config index from block fails. ErrLastConfigIndexFetch = &labeledError{ err: errors.New("failed to fetch last config block index"), label: "last_config_index_fetch", } )
Functions ¶
func MaxBlock ¶
MaxBlock returns the block with the highest block number between all the blocks in the input. Nil blocks are ignored. If all of them are nil, nil is returned.
func SourceLabel ¶ added in v1.0.4
SourceLabel returns the block source ID as a string. Used as a metric label for the source ID.
func ToQueueWithNoFT ¶
func ToQueueWithNoFT(ctx context.Context, noFtParams NoFTParameters) error
ToQueueWithNoFT connects to an orderer delivery server and delivers the stream to a queue (go channel). It provides a simple, no verification method, to load blocks the an orderer. It should not be used in production. It returns when an error occurs or when the context is done. It will attempt to reconnect on errors.
Types ¶
type Metrics ¶ added in v1.0.0
type Metrics struct {
// Stream Progress Metrics.
CurrentDataSourceID prometheus.Gauge
StreamBlockNumber *prometheus.GaugeVec // labels: stream_type
BlocksDeliveredTotal *prometheus.CounterVec // labels: stream_type, source_id
// Block Verification Metrics.
BlockVerificationSeconds *prometheus.HistogramVec // labels: stream_type, source_id, result
// Stream Lifecycle Metrics
StreamRestartsTotal *prometheus.CounterVec // labels: reason
StreamStartsTotal *prometheus.CounterVec // labels: stream_type, source_id
ActiveStreams *prometheus.GaugeVec // labels: stream_type, source_id
StreamErrorsTotal *prometheus.CounterVec // labels: stream_type, source_id, error_type
// Block Withholding Detection (BFT mode).
BlockGapGauge *prometheus.GaugeVec // labels: source_id
SuspicionRaisedTotal *prometheus.CounterVec // labels: source_id
SuspicionClearedTotal *prometheus.CounterVec // labels: source_id
SuspicionConfirmedTotal *prometheus.CounterVec // labels: source_id
TargetArrivalDeadline *prometheus.GaugeVec // labels: source_id
// Config Updates.
ConfigUpdatesTotal prometheus.Counter
ConfigBlockNumber prometheus.Gauge
}
Metrics holds all Prometheus metrics for the deliverorderer package. It tracks stream progress, block verification, timeouts, source suspicion, and error handling across data and header-only streams.
func NewMetrics ¶ added in v1.0.0
func NewMetrics(p *monitoring.Provider, params monitoring.MetricsParameters) *Metrics
NewMetrics creates a new Metrics instance with the specified provider and namespace.
type NoFTParameters ¶
type NoFTParameters struct {
ClientConfig *ordererdial.Config
NextBlockNum uint64
OutputBlock chan<- *common.Block
}
NoFTParameters needed for deliver to run.
type Parameters ¶
type Parameters struct {
FaultToleranceLevel string
TLS connection.TLSCredentials
TLSCertHash []byte
Retry *retry.Profile
Signer identity.SignerSerializer
LatestKnownConfig *common.Block
NextBlockVerificationConfig *common.Block
LastBlock *common.Block
OutputBlock chan<- *common.Block
OutputBlockWithSourceID chan<- *deliver.BlockWithSourceID
SuspicionGracePeriodPerBlock time.Duration
Metrics *Metrics
}
Parameters defines the configuration for fault-tolerant block delivery from Orderer organizations.
Fault Tolerance Level:
- BFT (Byzantine Fault Tolerance): Verifies blocks and monitors for block withholding attacks
- CFT (Crash Fault Tolerance): Verifies blocks only
- NO (No Fault Tolerance): No verification (not for production use)
- Empty: Defaults to BFT (highest fault tolerance)
Processing State:
- LastBlock: The most recently processed block (do NOT pass the genesis block here to allow the delivery to deliver it for processing)
- NextBlockVerificationConfig: Config block used to verify the next incoming block
- LatestKnownConfig: The newest known config block (can be ahead of NextBlockVerificationConfig) It enables connectivity when NextBlockVerificationConfig has stale orderer endpoints/credentials. This occurs in two scenarios: 1. A new organization joining long after genesis, where the starting config block has completely outdated endpoints. The caller provides current endpoints obtained out-of-band (e.g., via configuration file). 2. Session resumption after all old orderer endpoints were replaced while the data stream hadn't yet processed the config block with the new endpoints.
State Relationships:
- If LatestKnownConfig is not provided, NextBlockVerificationConfig is used as the latest config.
- If NextBlockVerificationConfig is not provided, policy verification starts only when a config block is delivered (LatestKnownConfig is NOT used for verification as it may not be relevant).
Output Channels:
- OutputBlock: Receives verified data blocks (without source information)
- OutputBlockWithSourceID: Receives verified data blocks with source orderer ID
- Note: At least one output channel must be provided
- Note: Both channels can be provided simultaneously if needed
Block Withholding Detection (BFT only): The system uses parallel streams to detect malicious orderers withholding blocks:
- One stream receives full blocks (data stream)
- Multiple streams receive block headers only (header-only streams)
Detection Process:
- When a header arrives ahead of the full block, the system suspects the current data stream source
- The system calculates the block gap (number of blocks the header stream is ahead)
- If the data stream doesn't catch up within (SuspicionGracePeriodPerBlock * block_gap) the system switches to another orderer
- After switching, the suspicion is cleared, allowing the new orderer time to establish connection and deliver blocks
SuspicionGracePeriodPerBlock should account for:
- Network latency between orderers and the client
- Time to deliver a single full block (not the block generation rate)
- Processing overhead for block validation
Note: "Time to deliver a full block" refers to the delivery time of existing blocks during catch-up, not the overall system's block generation capability.
If SuspicionGracePeriodPerBlock is too short, honest orderers will be arbitrarily suspected and the system will unnecessarily switch between orderers.
func LoadParametersFromConfig ¶
func LoadParametersFromConfig(c *ordererdial.Config) (p Parameters, err error)
LoadParametersFromConfig returns orderer delivery parameters and channel-ID from a given config.
type SessionInfo ¶
type SessionInfo struct {
LatestKnownConfig *common.Block
NextBlockVerificationConfig *common.Block
LastBlock *common.Block
}
SessionInfo represents the processing state of blocks to support recovery and resumption. See Parameters for detailed information about these fields.
func ToQueue ¶
func ToQueue(ctx context.Context, odp Parameters) (*SessionInfo, error)
ToQueue connects to an orderer delivery server, verifies blocks, and delivers them to a queue (go channel). It returns when an error occurs or when the context is done. It will attempt to reconnect on errors.
Source Files