Skip to content

Validation

ValidationMode

Bases: IntEnum

Result of validation processing.

Indicates whether a data structure (such as a block) passed validation, failed validation, or encountered an error during processing.

Source code in pbk/block.py 
16
17
18
19
20
21
22
23
24
25
class ValidationMode(IntEnum):
    """Result of validation processing.

    Indicates whether a data structure (such as a block) passed validation,
    failed validation, or encountered an error during processing.
    """

    VALID = 0  #: Validation succeeded
    INVALID = 1  #: Validation failed due to rule violations
    INTERNAL_ERROR = 2  #: An error occurred during validation processing

INTERNAL_ERROR class-attribute instance-attribute 

INTERNAL_ERROR = 2

INVALID class-attribute instance-attribute 

INVALID = 1

VALID class-attribute instance-attribute 

VALID = 0

BlockValidationResult

Bases: IntEnum

Specific reason why a block failed validation.

Provides detailed information about which validation rule was violated when a block is rejected. These results help diagnose why blocks fail to be accepted into the blockchain.

Source code in pbk/block.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class BlockValidationResult(IntEnum):
    """Specific reason why a block failed validation.

    Provides detailed information about which validation rule was violated
    when a block is rejected. These results help diagnose why blocks fail
    to be accepted into the blockchain.
    """

    UNSET = 0  #: Initial value, block has not yet been rejected
    CONSENSUS = 1  #: Invalid by consensus rules (excluding specific reasons below)
    CACHED_INVALID = 2  #: Block was previously cached as invalid, reason not stored
    INVALID_HEADER = 3  #: Invalid proof of work or timestamp too old
    MUTATED = 4  #: Block data didn't match the data committed to by the PoW
    MISSING_PREV = 5  #: The previous block this builds on is not available
    INVALID_PREV = 6  #: A block this one builds on is invalid
    TIME_FUTURE = 7  #: Block timestamp was more than 2 hours in the future
    HEADER_LOW_WORK = 8  #: Block header may be on a too-little-work chain

CACHED_INVALID class-attribute instance-attribute 

CACHED_INVALID = 2

CONSENSUS class-attribute instance-attribute 

CONSENSUS = 1

HEADER_LOW_WORK class-attribute instance-attribute 

HEADER_LOW_WORK = 8

INVALID_HEADER class-attribute instance-attribute 

INVALID_HEADER = 3

INVALID_PREV class-attribute instance-attribute 

INVALID_PREV = 6

MISSING_PREV class-attribute instance-attribute 

MISSING_PREV = 5

MUTATED class-attribute instance-attribute 

MUTATED = 4

TIME_FUTURE class-attribute instance-attribute 

TIME_FUTURE = 7

UNSET class-attribute instance-attribute 

UNSET = 0

BlockValidationState

Bases: KernelOpaquePtr

State of a block during validation.

Contains information about whether validation was successful and, if not, which specific validation step failed. This state is provided to validation interface callbacks to communicate detailed validation results.

Source code in pbk/block.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class BlockValidationState(KernelOpaquePtr):
    """State of a block during validation.

    Contains information about whether validation was successful and, if not,
    which specific validation step failed. This state is provided to validation
    interface callbacks to communicate detailed validation results.
    """

    _create_fn = k.btck_block_validation_state_create
    _destroy_fn = k.btck_block_validation_state_destroy
    _copy_fn = k.btck_block_validation_state_copy

    def __init__(self):
        """Create a block validation state."""
        super().__init__()

    @property
    def validation_mode(self) -> ValidationMode:
        """Overall validation result.

        Returns:
            Whether the block is valid, invalid, or encountered an error.
        """
        return ValidationMode(k.btck_block_validation_state_get_validation_mode(self))

    @property
    def block_validation_result(self) -> BlockValidationResult:
        """Specific validation failure reason.

        Returns:
            The granular reason why validation failed, or UNSET if valid.
        """
        return BlockValidationResult(
            k.btck_block_validation_state_get_block_validation_result(self)
        )

block_validation_result property 

block_validation_result: BlockValidationResult

Specific validation failure reason.

RETURNS DESCRIPTION
BlockValidationResult

The granular reason why validation failed, or UNSET if valid.

validation_mode property 

validation_mode: ValidationMode

Overall validation result.

RETURNS DESCRIPTION
ValidationMode

Whether the block is valid, invalid, or encountered an error.

__init__ 

__init__()

Create a block validation state.

Source code in pbk/block.py 
59
60
61
def __init__(self):
    """Create a block validation state."""
    super().__init__()

ValidationInterfaceCallbacks

Bases: btck_ValidationInterfaceCallbacks

Callbacks for receiving validation events.

These callbacks allow monitoring of block validation progress and results. Callbacks are invoked synchronously during validation and will block further validation execution until they complete, so they should execute quickly.

All callbacks are optional; only those passed as keyword arguments are registered, and any unspecified event is silently ignored.

Available callbacks, each invoked with (block, entry_or_state): - block_checked(block: Block, state: BlockValidationState): a block has been fully validated. state is only valid for the duration of the callback — do not retain it. - pow_valid_block(block: Block, entry: BlockTreeEntry): a block extends the header chain with valid PoW. - block_connected(block: Block, entry: BlockTreeEntry): a valid block was connected to the best chain. - block_disconnected(block: Block, entry: BlockTreeEntry): a block was disconnected during a reorg.

block is owned by the callback; entry is a view into the kernel's block index and remains valid for the kernel's lifetime.

Example

Register only block_disconnected:

cbs = ValidationInterfaceCallbacks( ... block_disconnected=lambda block, entry: print(entry.height) ... )

Source code in pbk/validation.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
class ValidationInterfaceCallbacks(k.btck_ValidationInterfaceCallbacks):
    """Callbacks for receiving validation events.

    These callbacks allow monitoring of block validation progress and results.
    Callbacks are invoked synchronously during validation and will block further
    validation execution until they complete, so they should execute quickly.

    All callbacks are optional; only those passed as keyword arguments are
    registered, and any unspecified event is silently ignored.

    Available callbacks, each invoked with `(block, entry_or_state)`:
      - `block_checked(block: Block, state: BlockValidationState)`:
        a block has been fully validated. `state` is only valid for the duration
        of the callback — do not retain it.
      - `pow_valid_block(block: Block, entry: BlockTreeEntry)`:
        a block extends the header chain with valid PoW.
      - `block_connected(block: Block, entry: BlockTreeEntry)`:
        a valid block was connected to the best chain.
      - `block_disconnected(block: Block, entry: BlockTreeEntry)`:
        a block was disconnected during a reorg.

    `block` is owned by the callback; `entry` is a view into the kernel's
    block index and remains valid for the kernel's lifetime.

    Example:
        Register only `block_disconnected`:

        >>> cbs = ValidationInterfaceCallbacks(
        ...     block_disconnected=lambda block, entry: print(entry.height)
        ... )
    """

    def __init__(
        self,
        **callbacks: Callable[..., None],
    ):
        """Create validation interface callbacks.

        Args:
            **callbacks: Callback functions for validation events, keyed by callback name
                         (e.g. ``block_disconnected=my_fn``). All are optional; omitted
                         callbacks are left unset.

        Raises:
            ValueError: If an unknown callback name is passed.
        """
        super().__init__()
        wrapped = {
            name: _VALIDATION_CALLBACK_WRAPPERS[name](fn)
            if name in _VALIDATION_CALLBACK_WRAPPERS
            else fn
            for name, fn in callbacks.items()
        }
        pbk.util.callbacks._initialize_callbacks(self, **wrapped)

__init__ 

__init__(**callbacks: Callable[..., None])

Create validation interface callbacks.

PARAMETER DESCRIPTION
**callbacks

Callback functions for validation events, keyed by callback name (e.g. block_disconnected=my_fn). All are optional; omitted callbacks are left unset.

TYPE: Callable[..., None] DEFAULT: {}

RAISES DESCRIPTION
ValueError

If an unknown callback name is passed.
Source code in pbk/validation.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def __init__(
    self,
    **callbacks: Callable[..., None],
):
    """Create validation interface callbacks.

    Args:
        **callbacks: Callback functions for validation events, keyed by callback name
                     (e.g. ``block_disconnected=my_fn``). All are optional; omitted
                     callbacks are left unset.

    Raises:
        ValueError: If an unknown callback name is passed.
    """
    super().__init__()
    wrapped = {
        name: _VALIDATION_CALLBACK_WRAPPERS[name](fn)
        if name in _VALIDATION_CALLBACK_WRAPPERS
        else fn
        for name, fn in callbacks.items()
    }
    pbk.util.callbacks._initialize_callbacks(self, **wrapped)