Skip to content

Context API

ContextOptions

Bases: KernelOpaquePtr

Options for creating a new kernel context.

Once a kernel context has been created from this options object, it may be destroyed. Changes made to the options after the kernel context has been created will not be reflected on the kernel context.

Source code in pbk/context.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
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
class ContextOptions(KernelOpaquePtr):
    """Options for creating a new kernel context.

    Once a kernel context has been created from this options object, it may be destroyed. Changes
    made to the options after the kernel context has been created will not be reflected on the
    kernel context.
    """

    _create_fn = k.btck_context_options_create
    _destroy_fn = k.btck_context_options_destroy

    def __init__(self):
        """Create context options."""
        super().__init__()
        self._notifications: NotificationInterfaceCallbacks | None = None
        self._validation_callbacks: ValidationInterfaceCallbacks | None = None

    def set_chainparams(self, chain_parameters: "ChainParameters") -> None:
        """Sets the chain parameters for the context options.

        Args:
            chain_parameters: Chain parameters to set.
        """
        k.btck_context_options_set_chainparams(self, chain_parameters)

    def set_notifications(
        self, notifications: "NotificationInterfaceCallbacks"
    ) -> None:
        """Sets the kernel notifications for the context options.

        Args:
            notifications: Notification callbacks to set.
        """
        k.btck_context_options_set_notifications(self, notifications)
        self._notifications = notifications

    def set_validation_interface(
        self, interface_callbacks: "ValidationInterfaceCallbacks"
    ) -> None:
        """Sets the validation interface callbacks for the context options.

        Args:
            interface_callbacks: Validation callbacks to set.
        """
        k.btck_context_options_set_validation_interface(self, interface_callbacks)
        self._validation_callbacks = interface_callbacks

__init__ 

__init__()

Create context options.

Source code in pbk/context.py 
23
24
25
26
27
def __init__(self):
    """Create context options."""
    super().__init__()
    self._notifications: NotificationInterfaceCallbacks | None = None
    self._validation_callbacks: ValidationInterfaceCallbacks | None = None

set_chainparams 

set_chainparams(chain_parameters: ChainParameters) -> None

Sets the chain parameters for the context options.

PARAMETER DESCRIPTION
chain_parameters

Chain parameters to set.

TYPE: ChainParameters

Source code in pbk/context.py 
29
30
31
32
33
34
35
def set_chainparams(self, chain_parameters: "ChainParameters") -> None:
    """Sets the chain parameters for the context options.

    Args:
        chain_parameters: Chain parameters to set.
    """
    k.btck_context_options_set_chainparams(self, chain_parameters)

set_notifications 

set_notifications(notifications: NotificationInterfaceCallbacks) -> None

Sets the kernel notifications for the context options.

PARAMETER DESCRIPTION
notifications

Notification callbacks to set.

TYPE: NotificationInterfaceCallbacks

Source code in pbk/context.py 
37
38
39
40
41
42
43
44
45
46
def set_notifications(
    self, notifications: "NotificationInterfaceCallbacks"
) -> None:
    """Sets the kernel notifications for the context options.

    Args:
        notifications: Notification callbacks to set.
    """
    k.btck_context_options_set_notifications(self, notifications)
    self._notifications = notifications

set_validation_interface 

set_validation_interface(interface_callbacks: ValidationInterfaceCallbacks) -> None

Sets the validation interface callbacks for the context options.

PARAMETER DESCRIPTION
interface_callbacks

Validation callbacks to set.

TYPE: ValidationInterfaceCallbacks

Source code in pbk/context.py 
48
49
50
51
52
53
54
55
56
57
def set_validation_interface(
    self, interface_callbacks: "ValidationInterfaceCallbacks"
) -> None:
    """Sets the validation interface callbacks for the context options.

    Args:
        interface_callbacks: Validation callbacks to set.
    """
    k.btck_context_options_set_validation_interface(self, interface_callbacks)
    self._validation_callbacks = interface_callbacks

Context

Bases: KernelOpaquePtr

The kernel context is used to initialize internal state and hold the chain parameters and callbacks for handling error and validation events.

Source code in pbk/context.py 
 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
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class Context(KernelOpaquePtr):
    """The kernel context is used to initialize internal state and hold the chain
    parameters and callbacks for handling error and validation events.
    """

    _create_fn = k.btck_context_create
    _destroy_fn = k.btck_context_destroy
    _copy_fn = k.btck_context_copy

    def __init__(self, options: ContextOptions):
        """Create a kernel context.

        Args:
            options: Context options to use.
        """
        super().__init__(options)
        self._notifications = options._notifications
        self._validation_callbacks = options._validation_callbacks

    def __copy__(self) -> "Context":
        """Return an independent handle to the same kernel context.

        Propagates Python-side keepalives for the notification and validation
        callbacks: the kernel stores raw function pointers into ctypes
        trampolines owned by these Python objects, so the copy must keep them
        alive even if the source handle is dropped.
        """
        copy = super().__copy__()
        copy._notifications = self._notifications
        copy._validation_callbacks = self._validation_callbacks
        return copy

    def interrupt(self) -> int:
        """Interrupt long-running validation functions. Useful for operations like reindexing,
        importing or processing blocks.

        Returns:
            0 if interrupt was successful, non-zero otherwise
        """
        return k.btck_context_interrupt(self)

    def __repr__(self) -> str:
        """Return a string representation of the context."""
        return f"<Context at {hex(id(self))}>"

__copy__ 

__copy__() -> Context

Return an independent handle to the same kernel context.

Propagates Python-side keepalives for the notification and validation callbacks: the kernel stores raw function pointers into ctypes trampolines owned by these Python objects, so the copy must keep them alive even if the source handle is dropped.

Source code in pbk/context.py 
79
80
81
82
83
84
85
86
87
88
89
90
def __copy__(self) -> "Context":
    """Return an independent handle to the same kernel context.

    Propagates Python-side keepalives for the notification and validation
    callbacks: the kernel stores raw function pointers into ctypes
    trampolines owned by these Python objects, so the copy must keep them
    alive even if the source handle is dropped.
    """
    copy = super().__copy__()
    copy._notifications = self._notifications
    copy._validation_callbacks = self._validation_callbacks
    return copy

__init__ 

__init__(options: ContextOptions)

Create a kernel context.

PARAMETER DESCRIPTION
options

Context options to use.

TYPE: ContextOptions

Source code in pbk/context.py 
69
70
71
72
73
74
75
76
77
def __init__(self, options: ContextOptions):
    """Create a kernel context.

    Args:
        options: Context options to use.
    """
    super().__init__(options)
    self._notifications = options._notifications
    self._validation_callbacks = options._validation_callbacks

__repr__ 

__repr__() -> str

Return a string representation of the context.

Source code in pbk/context.py 
101
102
103
def __repr__(self) -> str:
    """Return a string representation of the context."""
    return f"<Context at {hex(id(self))}>"

interrupt 

interrupt() -> int

Interrupt long-running validation functions. Useful for operations like reindexing, importing or processing blocks.

RETURNS DESCRIPTION
int

0 if interrupt was successful, non-zero otherwise
Source code in pbk/context.py 
92
93
94
95
96
97
98
99
def interrupt(self) -> int:
    """Interrupt long-running validation functions. Useful for operations like reindexing,
    importing or processing blocks.

    Returns:
        0 if interrupt was successful, non-zero otherwise
    """
    return k.btck_context_interrupt(self)

make_context 

make_context(chain_type: ChainType = ChainType.REGTEST, validation_callbacks: ValidationInterfaceCallbacks | None = None) -> Context

Build a Context for the given chain type.

PARAMETER DESCRIPTION
chain_type

The chain parameters to use.

TYPE: ChainType DEFAULT: REGTEST

validation_callbacks

Optional callbacks to receive validation events (block connected, disconnected, etc.). See ValidationInterfaceCallbacks for the available events.

TYPE: ValidationInterfaceCallbacks | None DEFAULT: None

RETURNS DESCRIPTION
Context

A new Context. Owned handle.
Source code in pbk/__init__.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
def make_context(
    chain_type: ChainType = ChainType.REGTEST,
    validation_callbacks: ValidationInterfaceCallbacks | None = None,
) -> Context:
    """Build a `Context` for the given chain type.

    Args:
        chain_type: The chain parameters to use.
        validation_callbacks: Optional callbacks to receive validation events
            (block connected, disconnected, etc.). See
            `ValidationInterfaceCallbacks` for the available events.

    Returns:
        A new `Context`. Owned handle.
    """
    chain_params = ChainParameters(chain_type)
    opts = ContextOptions()
    opts.set_chainparams(chain_params)
    if validation_callbacks is not None:
        opts.set_validation_interface(validation_callbacks)
    return Context(opts)