Skip to content

Validation

ValidationMode

Bases: IntEnum

Result of validation processing.

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

Source code in pbk/validation.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class ValidationMode(IntEnum):
    """Result of validation processing.

    Indicates whether a data structure (such as a block or transaction)
    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

An error occurred during validation processing

INVALID class-attribute instance-attribute 

INVALID = 1

Validation failed due to rule violations

VALID class-attribute instance-attribute 

VALID = 0

Validation succeeded

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 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
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 any below reasons)"""

    CACHED_INVALID = 2
    """This block was cached as being invalid and we didn't store the reason why"""

    INVALID_HEADER = 3
    """Invalid proof of work or time too old"""

    MUTATED = 4
    """The block's data didn't match the data committed to by the PoW"""

    MISSING_PREV = 5
    """We don't have the previous block the checked one is built on"""

    INVALID_PREV = 6
    """A block this one builds on is invalid"""

    TIME_FUTURE = 7
    """Block timestamp was > 2 hours in the future (or our clock is bad)"""

    HEADER_LOW_WORK = 8
    """The block header may be on a too-little-work chain"""

CACHED_INVALID class-attribute instance-attribute 

CACHED_INVALID = 2

This block was cached as being invalid and we didn't store the reason why

CONSENSUS class-attribute instance-attribute 

CONSENSUS = 1

Invalid by consensus rules (excluding any below reasons)

HEADER_LOW_WORK class-attribute instance-attribute 

HEADER_LOW_WORK = 8

The block header may be on a too-little-work chain

INVALID_HEADER class-attribute instance-attribute 

INVALID_HEADER = 3

Invalid proof of work or time too old

INVALID_PREV class-attribute instance-attribute 

INVALID_PREV = 6

A block this one builds on is invalid

MISSING_PREV class-attribute instance-attribute 

MISSING_PREV = 5

We don't have the previous block the checked one is built on

MUTATED class-attribute instance-attribute 

MUTATED = 4

The block's data didn't match the data committed to by the PoW

TIME_FUTURE class-attribute instance-attribute 

TIME_FUTURE = 7

Block timestamp was > 2 hours in the future (or our clock is bad)

UNSET class-attribute instance-attribute 

UNSET = 0

Initial value. Block has not yet been rejected

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/validation.py 
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
89
90
91
92
93
94
95
96
97
98
99
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)
        )

    def __repr__(self) -> str:
        """Return a string representation of the block validation state."""
        return f"<BlockValidationState mode={self.validation_mode.name} result={self.block_validation_result.name}>"

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/validation.py 
73
74
75
def __init__(self):
    """Create a block validation state."""
    super().__init__()

__repr__ 

__repr__() -> str

Return a string representation of the block validation state.

Source code in pbk/validation.py 
97
98
99
def __repr__(self) -> str:
    """Return a string representation of the block validation state."""
    return f"<BlockValidationState mode={self.validation_mode.name} result={self.block_validation_result.name}>"

TxValidationResult

Bases: IntEnum

Specific reason why a transaction failed validation.

The subset of values that can occur depends on which validation function was used.

Source code in pbk/validation.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
class TxValidationResult(IntEnum):
    """Specific reason why a transaction failed validation.

    The subset of values that can occur depends on which validation
    function was used.
    """

    UNSET = 0
    """Initial value. Tx has not yet been rejected"""

    CONSENSUS = 1
    """Invalid by consensus rules"""

    INPUTS_NOT_STANDARD = 2
    """Inputs (covered by txid) failed policy rules"""

    NOT_STANDARD = 3
    """Otherwise didn't meet local policy rules"""

    MISSING_INPUTS = 4
    """Transaction was missing some of its inputs"""

    PREMATURE_SPEND = 5
    """Transaction spends a coinbase too early, or violates locktime/sequence locks"""

    WITNESS_MUTATED = 6
    """Witness may have been malleated or is prior to SegWit activation"""

    WITNESS_STRIPPED = 7
    """Transaction is missing a witness"""

    CONFLICT = 8
    """Tx already in mempool or conflicts with a tx in the chain"""

    MEMPOOL_POLICY = 9
    """Violated mempool's fee/size/descendant/RBF/etc limits"""

    NO_MEMPOOL = 10
    """This node does not have a mempool so can't validate the transaction"""

    RECONSIDERABLE = 11
    """Fails some policy, but might be acceptable if submitted in a (different) package"""

    UNKNOWN = 12
    """Transaction was not validated because package failed"""

CONFLICT class-attribute instance-attribute 

CONFLICT = 8

Tx already in mempool or conflicts with a tx in the chain

CONSENSUS class-attribute instance-attribute 

CONSENSUS = 1

Invalid by consensus rules

INPUTS_NOT_STANDARD class-attribute instance-attribute 

INPUTS_NOT_STANDARD = 2

Inputs (covered by txid) failed policy rules

MEMPOOL_POLICY class-attribute instance-attribute 

MEMPOOL_POLICY = 9

Violated mempool's fee/size/descendant/RBF/etc limits

MISSING_INPUTS class-attribute instance-attribute 

MISSING_INPUTS = 4

Transaction was missing some of its inputs

NOT_STANDARD class-attribute instance-attribute 

NOT_STANDARD = 3

Otherwise didn't meet local policy rules

NO_MEMPOOL class-attribute instance-attribute 

NO_MEMPOOL = 10

This node does not have a mempool so can't validate the transaction

PREMATURE_SPEND class-attribute instance-attribute 

PREMATURE_SPEND = 5

Transaction spends a coinbase too early, or violates locktime/sequence locks

RECONSIDERABLE class-attribute instance-attribute 

RECONSIDERABLE = 11

Fails some policy, but might be acceptable if submitted in a (different) package

UNKNOWN class-attribute instance-attribute 

UNKNOWN = 12

Transaction was not validated because package failed

UNSET class-attribute instance-attribute 

UNSET = 0

Initial value. Tx has not yet been rejected

WITNESS_MUTATED class-attribute instance-attribute 

WITNESS_MUTATED = 6

Witness may have been malleated or is prior to SegWit activation

WITNESS_STRIPPED class-attribute instance-attribute 

WITNESS_STRIPPED = 7

Transaction is missing a witness

TxValidationState

Bases: KernelOpaquePtr

State of a transaction during validation.

Contains information about whether validation was successful and, if not, which specific validation step failed.

Source code in pbk/validation.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
class TxValidationState(KernelOpaquePtr):
    """State of a transaction during validation.

    Contains information about whether validation was successful and, if not,
    which specific validation step failed.
    """

    _create_fn = k.btck_tx_validation_state_create
    _destroy_fn = k.btck_tx_validation_state_destroy

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

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

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

    @property
    def tx_validation_result(self) -> TxValidationResult:
        """Specific validation failure reason.

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

    def __repr__(self) -> str:
        """Return a string representation of the transaction validation state."""
        return f"<TxValidationState mode={self.validation_mode.name} result={self.tx_validation_result.name}>"

tx_validation_result property 

tx_validation_result: TxValidationResult

Specific validation failure reason.

RETURNS DESCRIPTION
TxValidationResult

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

validation_mode property 

validation_mode: ValidationMode

Overall validation result.

RETURNS DESCRIPTION
ValidationMode

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

__init__ 

__init__()

Create a transaction validation state.

Source code in pbk/validation.py 
159
160
161
def __init__(self):
    """Create a transaction validation state."""
    super().__init__()

__repr__ 

__repr__() -> str

Return a string representation of the transaction validation state.

Source code in pbk/validation.py 
183
184
185
def __repr__(self) -> str:
    """Return a string representation of the transaction validation state."""
    return f"<TxValidationState mode={self.validation_mode.name} result={self.tx_validation_result.name}>"

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_interface.py 
32
33
34
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
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.capi.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_interface.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
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.capi.callbacks._initialize_callbacks(self, **wrapped)