Skip to content

Script

ScriptVerificationFlags

Bases: IntEnum

Script verification flags that may be composed with each other.

These flags control which validation rules are enforced during script verification. Multiple flags can be combined using bitwise OR operations.

Source code in pbk/script.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class ScriptVerificationFlags(IntEnum):
    """Script verification flags that may be composed with each other.

    These flags control which validation rules are enforced during script
    verification. Multiple flags can be combined using bitwise OR operations.
    """

    NONE = 0  #: No verification flags
    P2SH = 1 << 0  #: Evaluate P2SH subscripts (BIP16)
    DERSIG = 1 << 2  #: Enforce strict DER signature encoding (BIP66)
    NULLDUMMY = 1 << 4  #: Enforce NULLDUMMY rule (BIP147)
    CHECKLOCKTIMEVERIFY = 1 << 9  #: Enable CHECKLOCKTIMEVERIFY opcode (BIP65)
    CHECKSEQUENCEVERIFY = 1 << 10  #: Enable CHECKSEQUENCEVERIFY opcode (BIP112)
    WITNESS = 1 << 11  #: Enable Segregated Witness (BIP141)
    TAPROOT = 1 << 17  #: Enable Taproot (BIP341 & BIP342)
    ALL = (  #: All verification flags combined
        P2SH
        | DERSIG
        | NULLDUMMY
        | CHECKLOCKTIMEVERIFY
        | CHECKSEQUENCEVERIFY
        | WITNESS
        | TAPROOT
    )

ALL class-attribute instance-attribute 

ALL = P2SH | DERSIG | NULLDUMMY | CHECKLOCKTIMEVERIFY | CHECKSEQUENCEVERIFY | WITNESS | TAPROOT

CHECKLOCKTIMEVERIFY class-attribute instance-attribute 

CHECKLOCKTIMEVERIFY = 1 << 9

CHECKSEQUENCEVERIFY class-attribute instance-attribute 

CHECKSEQUENCEVERIFY = 1 << 10

DERSIG class-attribute instance-attribute 

DERSIG = 1 << 2

NONE class-attribute instance-attribute 

NONE = 0

NULLDUMMY class-attribute instance-attribute 

NULLDUMMY = 1 << 4

P2SH class-attribute instance-attribute 

P2SH = 1 << 0

TAPROOT class-attribute instance-attribute 

TAPROOT = 1 << 17

WITNESS class-attribute instance-attribute 

WITNESS = 1 << 11

ScriptVerifyStatus

Bases: IntEnum

Status codes returned by script verification.

These codes indicate the result of script verification, including success, various error conditions, and validation failures.

Source code in pbk/script.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class ScriptVerifyStatus(IntEnum):
    """Status codes returned by script verification.

    These codes indicate the result of script verification, including
    success, various error conditions, and validation failures.
    """

    OK = 0  #: Verification succeeded
    ERROR_INVALID_FLAGS_COMBINATION = (
        1  #: The verification flags were combined in an invalid way
    )
    ERROR_SPENT_OUTPUTS_REQUIRED = (
        2  #: The taproot flag requires valid spent outputs to be provided
    )

ERROR_INVALID_FLAGS_COMBINATION class-attribute instance-attribute 

ERROR_INVALID_FLAGS_COMBINATION = 1

ERROR_SPENT_OUTPUTS_REQUIRED class-attribute instance-attribute 

ERROR_SPENT_OUTPUTS_REQUIRED = 2

OK class-attribute instance-attribute 

OK = 0

ScriptPubkey

Bases: KernelOpaquePtr

A Bitcoin script defining spending conditions for an output.

Source code in pbk/script.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
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
147
148
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
class ScriptPubkey(KernelOpaquePtr):
    """A Bitcoin script defining spending conditions for an output."""

    _create_fn = k.btck_script_pubkey_create
    _destroy_fn = k.btck_script_pubkey_destroy

    def __init__(self, data: bytes):
        """Create a script pubkey from raw script data.

        Args:
            data: The script pubkey data containing opcodes and operands.

        Raises:
            RuntimeError: If the C constructor fails (propagated from base class).
        """
        super().__init__((ctypes.c_ubyte * len(data))(*data), len(data))

    def __bytes__(self) -> bytes:
        """Serialize the script pubkey to bytes.

        Returns:
            The raw script data.
        """
        writer = ByteWriter()
        return writer.write(k.btck_script_pubkey_to_bytes, self)

    def __repr__(self) -> str:
        """Return a string representation of the script pubkey."""
        hex_str = str(self)
        preview = hex_str[:32] + "..." if len(hex_str) > 32 else hex_str
        return f"<ScriptPubkey len={len(bytes(self))} hex={preview}>"

    def __str__(self) -> str:
        """Get the hexadecimal representation of the script.

        Returns:
            The script data as a hex string.
        """
        return bytes(self).hex()

    def verify(
        self,
        amount: int,
        tx_to: "Transaction",
        spent_outputs: list["TransactionOutput"] | None,
        input_index: int,
        flags: int,
    ) -> bool:
        """Verify that a transaction input correctly spends this script pubkey.

        This function validates whether the input at the specified index in the
        spending transaction satisfies the conditions defined by the script pubkey.
        The verification process depends on the flags provided, which control which
        consensus rules are enforced.

        Args:
            amount: The value of the output being spent, in satoshis. Required
                when VERIFY_WITNESS flag is set.
            tx_to: The transaction that is attempting to spend the output.
            spent_outputs: All outputs being spent by the transaction. Required
                when VERIFY_TAPROOT flag is set, otherwise can be None.
            input_index: The zero-based index of the input in `tx_to` that is
                spending the script pubkey.
            flags: Bitfield of ScriptFlags controlling which validation rules to
                enforce. Use ScriptFlags values combined with bitwise OR.

        Returns:
            True if the script verification succeeds.

        Raises:
            ScriptVerifyException: If script verification fails. The exception
                contains a status code indicating the specific failure reason.
        """
        spent_outputs_array = (
            (ctypes.POINTER(k.btck_TransactionOutput) * len(spent_outputs))(
                *[output._as_parameter_ for output in spent_outputs]
            )
            if spent_outputs
            else None
        )
        spent_outputs_len = len(spent_outputs) if spent_outputs else 0
        k_status = k.btck_ScriptVerifyStatus(ScriptVerifyStatus.OK)
        success = k.btck_script_pubkey_verify(
            self,
            amount,
            tx_to,
            spent_outputs_array,
            spent_outputs_len,
            ctypes.c_uint32(input_index),
            ctypes.c_uint32(flags),
            k_status,
        )

        status = ScriptVerifyStatus(k_status.value)
        if not success and status != ScriptVerifyStatus.OK:
            raise ScriptVerifyException(status)

        return success

__bytes__ 

__bytes__() -> bytes

Serialize the script pubkey to bytes.

RETURNS DESCRIPTION
bytes

The raw script data.
Source code in pbk/script.py 
100
101
102
103
104
105
106
107
def __bytes__(self) -> bytes:
    """Serialize the script pubkey to bytes.

    Returns:
        The raw script data.
    """
    writer = ByteWriter()
    return writer.write(k.btck_script_pubkey_to_bytes, self)

__init__ 

__init__(data: bytes)

Create a script pubkey from raw script data.

PARAMETER DESCRIPTION
data

The script pubkey data containing opcodes and operands.

TYPE: bytes

RAISES DESCRIPTION
RuntimeError

If the C constructor fails (propagated from base class).
Source code in pbk/script.py 
89
90
91
92
93
94
95
96
97
98
def __init__(self, data: bytes):
    """Create a script pubkey from raw script data.

    Args:
        data: The script pubkey data containing opcodes and operands.

    Raises:
        RuntimeError: If the C constructor fails (propagated from base class).
    """
    super().__init__((ctypes.c_ubyte * len(data))(*data), len(data))

__repr__ 

__repr__() -> str

Return a string representation of the script pubkey.

Source code in pbk/script.py 
109
110
111
112
113
def __repr__(self) -> str:
    """Return a string representation of the script pubkey."""
    hex_str = str(self)
    preview = hex_str[:32] + "..." if len(hex_str) > 32 else hex_str
    return f"<ScriptPubkey len={len(bytes(self))} hex={preview}>"

__str__ 

__str__() -> str

Get the hexadecimal representation of the script.

RETURNS DESCRIPTION
str

The script data as a hex string.
Source code in pbk/script.py 
115
116
117
118
119
120
121
def __str__(self) -> str:
    """Get the hexadecimal representation of the script.

    Returns:
        The script data as a hex string.
    """
    return bytes(self).hex()

verify 

verify(amount: int, tx_to: Transaction, spent_outputs: list[TransactionOutput] | None, input_index: int, flags: int) -> bool

Verify that a transaction input correctly spends this script pubkey.

This function validates whether the input at the specified index in the spending transaction satisfies the conditions defined by the script pubkey. The verification process depends on the flags provided, which control which consensus rules are enforced.

PARAMETER DESCRIPTION
amount

The value of the output being spent, in satoshis. Required when VERIFY_WITNESS flag is set.

TYPE: int

tx_to

The transaction that is attempting to spend the output.

TYPE: Transaction

spent_outputs

All outputs being spent by the transaction. Required when VERIFY_TAPROOT flag is set, otherwise can be None.

TYPE: list[TransactionOutput] | None

input_index

The zero-based index of the input in tx_to that is spending the script pubkey.

TYPE: int

flags

Bitfield of ScriptFlags controlling which validation rules to enforce. Use ScriptFlags values combined with bitwise OR.

TYPE: int

RETURNS DESCRIPTION
bool

True if the script verification succeeds.
RAISES DESCRIPTION
ScriptVerifyException

If script verification fails. The exception contains a status code indicating the specific failure reason.
Source code in pbk/script.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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
def verify(
    self,
    amount: int,
    tx_to: "Transaction",
    spent_outputs: list["TransactionOutput"] | None,
    input_index: int,
    flags: int,
) -> bool:
    """Verify that a transaction input correctly spends this script pubkey.

    This function validates whether the input at the specified index in the
    spending transaction satisfies the conditions defined by the script pubkey.
    The verification process depends on the flags provided, which control which
    consensus rules are enforced.

    Args:
        amount: The value of the output being spent, in satoshis. Required
            when VERIFY_WITNESS flag is set.
        tx_to: The transaction that is attempting to spend the output.
        spent_outputs: All outputs being spent by the transaction. Required
            when VERIFY_TAPROOT flag is set, otherwise can be None.
        input_index: The zero-based index of the input in `tx_to` that is
            spending the script pubkey.
        flags: Bitfield of ScriptFlags controlling which validation rules to
            enforce. Use ScriptFlags values combined with bitwise OR.

    Returns:
        True if the script verification succeeds.

    Raises:
        ScriptVerifyException: If script verification fails. The exception
            contains a status code indicating the specific failure reason.
    """
    spent_outputs_array = (
        (ctypes.POINTER(k.btck_TransactionOutput) * len(spent_outputs))(
            *[output._as_parameter_ for output in spent_outputs]
        )
        if spent_outputs
        else None
    )
    spent_outputs_len = len(spent_outputs) if spent_outputs else 0
    k_status = k.btck_ScriptVerifyStatus(ScriptVerifyStatus.OK)
    success = k.btck_script_pubkey_verify(
        self,
        amount,
        tx_to,
        spent_outputs_array,
        spent_outputs_len,
        ctypes.c_uint32(input_index),
        ctypes.c_uint32(flags),
        k_status,
    )

    status = ScriptVerifyStatus(k_status.value)
    if not success and status != ScriptVerifyStatus.OK:
        raise ScriptVerifyException(status)

    return success