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/validation.py 
10
11
12
13
14
15
16
17
18
19
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/validation.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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.

Note

BlockValidationState instances cannot be directly constructed. They are obtained from validation interface callbacks.

Source code in pbk/validation.py 
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
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.

    Note:
        BlockValidationState instances cannot be directly constructed. They are
        obtained from validation interface callbacks.
    """

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

        Returns:
            Whether the block is valid, invalid, or encountered an error.
        """
        return 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 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.

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.

Available callbacks
  • block_checked: Called when a block has been fully validated with results
  • pow_valid_block: Called when a block extends the header chain with valid PoW
  • block_connected: Called when a valid block is connected to the best chain
  • block_disconnected: Called when a block is disconnected during a reorg
Source code in pbk/validation.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
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.

    Available callbacks:
      - `block_checked`: Called when a block has been fully validated with results
      - `pow_valid_block`: Called when a block extends the header chain with valid PoW
      - `block_connected`: Called when a valid block is connected to the best chain
      - `block_disconnected`: Called when a block is disconnected during a reorg
    """

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

        Args:
            user_data: Optional user-defined data passed to all callbacks.
            **callbacks: Callback functions for validation events. The key is the name of the callback,
                         the value the callback function.
        """
        super().__init__()
        pbk.util.callbacks._initialize_callbacks(self, user_data, **callbacks)

__init__ 

__init__(user_data: UserData | None = None, **callbacks: Callable[..., None])

Create validation interface callbacks.

PARAMETER DESCRIPTION
user_data

Optional user-defined data passed to all callbacks.

TYPE: UserData | None DEFAULT: None

**callbacks

Callback functions for validation events. The key is the name of the callback, the value the callback function.

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

Source code in pbk/validation.py 
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def __init__(
    self,
    user_data: UserData | None = None,
    **callbacks: Callable[..., None],
):
    """Create validation interface callbacks.

    Args:
        user_data: Optional user-defined data passed to all callbacks.
        **callbacks: Callback functions for validation events. The key is the name of the callback,
                     the value the callback function.
    """
    super().__init__()
    pbk.util.callbacks._initialize_callbacks(self, user_data, **callbacks)