Skip to content

Spec

Documentation for tests/cancun/eip4844_blobs/spec.py.

Defines EIP-4844 specification constants and functions.

Spec dataclass

Parameters from the EIP-4844 specifications as defined at https://eips.ethereum.org/EIPS/eip-4844#parameters

If the parameter is not currently used within the tests, it is commented out.

Source code in tests/cancun/eip4844_blobs/spec.py
 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
 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
@dataclass(frozen=True)
class Spec:
    """
    Parameters from the EIP-4844 specifications as defined at
    https://eips.ethereum.org/EIPS/eip-4844#parameters

    If the parameter is not currently used within the tests, it is commented
    out.
    """

    BLOB_TX_TYPE = 0x03
    FIELD_ELEMENTS_PER_BLOB = 4096
    BLS_MODULUS = 0x73EDA753299D7D483339D80809A1D80553BDA402FFFE5BFEFFFFFFFF00000001
    BLOB_COMMITMENT_VERSION_KZG = 1
    POINT_EVALUATION_PRECOMPILE_ADDRESS = 20
    POINT_EVALUATION_PRECOMPILE_GAS = 50_000
    MAX_DATA_GAS_PER_BLOCK = 786432
    TARGET_DATA_GAS_PER_BLOCK = 393216
    MIN_DATA_GASPRICE = 1
    DATA_GASPRICE_UPDATE_FRACTION = 3338477
    # MAX_VERSIONED_HASHES_LIST_SIZE = 2**24
    # MAX_CALLDATA_SIZE = 2**24
    # MAX_ACCESS_LIST_SIZE = 2**24
    # MAX_ACCESS_LIST_STORAGE_KEYS = 2**24
    # MAX_TX_WRAP_COMMITMENTS = 2**12
    # LIMIT_BLOBS_PER_TX = 2**12
    DATA_GAS_PER_BLOB = 2**17
    HASH_OPCODE_BYTE = 0x49
    HASH_GAS_COST = 3

    @classmethod
    def kzg_to_versioned_hash(
        cls,
        kzg_commitment: bytes | int,  # 48 bytes
        blob_commitment_version_kzg: Optional[bytes | int] = None,
    ) -> bytes:
        """
        Calculates the versioned hash for a given KZG commitment.
        """
        if blob_commitment_version_kzg is None:
            blob_commitment_version_kzg = cls.BLOB_COMMITMENT_VERSION_KZG
        if isinstance(kzg_commitment, int):
            kzg_commitment = kzg_commitment.to_bytes(48, "big")
        if isinstance(blob_commitment_version_kzg, int):
            blob_commitment_version_kzg = blob_commitment_version_kzg.to_bytes(1, "big")
        return blob_commitment_version_kzg + sha256(kzg_commitment).digest()[1:]

    @classmethod
    def fake_exponential(cls, factor: int, numerator: int, denominator: int) -> int:
        """
        Used to calculate the data gas cost.
        """
        i = 1
        output = 0
        numerator_accumulator = factor * denominator
        while numerator_accumulator > 0:
            output += numerator_accumulator
            numerator_accumulator = (numerator_accumulator * numerator) // (denominator * i)
            i += 1
        return output // denominator

    @classmethod
    def calc_excess_data_gas(cls, parent: BlockHeaderDataGasFields) -> int:
        """
        Calculate the excess data gas for a block given the excess data gas
        and data gas used from the parent block header.
        """
        if parent.excess_data_gas + parent.data_gas_used < cls.TARGET_DATA_GAS_PER_BLOCK:
            return 0
        else:
            return parent.excess_data_gas + parent.data_gas_used - cls.TARGET_DATA_GAS_PER_BLOCK

    # Note: Currently unused.
    # @classmethod
    # def get_total_data_gas(cls, tx: Transaction) -> int:
    #     """
    #     Calculate the total data gas for a transaction.
    #     """
    #     if tx.blob_versioned_hashes is None:
    #         return 0
    #     return cls.DATA_GAS_PER_BLOB * len(tx.blob_versioned_hashes)

    @classmethod
    def get_data_gasprice(cls, *, excess_data_gas: int) -> int:
        """
        Calculate the data gas price from the excess.
        """
        return cls.fake_exponential(
            cls.MIN_DATA_GASPRICE,
            excess_data_gas,
            cls.DATA_GASPRICE_UPDATE_FRACTION,
        )

SpecHelpers dataclass

Define parameters and helper functions that are tightly coupled to the 4844 spec but not strictly part of it.

Source code in tests/cancun/eip4844_blobs/spec.py
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
181
182
183
184
185
@dataclass(frozen=True)
class SpecHelpers:
    """
    Define parameters and helper functions that are tightly coupled to the 4844
    spec but not strictly part of it.
    """

    BYTES_PER_FIELD_ELEMENT = 32

    @classmethod
    def max_blobs_per_block(cls) -> int:  # MAX_BLOBS_PER_BLOCK =
        """
        Returns the maximum number of blobs per block.
        """
        return Spec.MAX_DATA_GAS_PER_BLOCK // Spec.DATA_GAS_PER_BLOB

    @classmethod
    def target_blobs_per_block(cls) -> int:
        """
        Returns the target number of blobs per block.
        """
        return Spec.TARGET_DATA_GAS_PER_BLOCK // Spec.DATA_GAS_PER_BLOB

    @classmethod
    def calc_excess_data_gas_from_blob_count(
        cls, parent_excess_data_gas: int, parent_blob_count: int
    ) -> int:
        """
        Calculate the excess data gas for a block given the parent excess data gas
        and the number of blobs in the block.
        """
        parent_consumed_data_gas = parent_blob_count * Spec.DATA_GAS_PER_BLOB
        return Spec.calc_excess_data_gas(
            BlockHeaderDataGasFields(parent_excess_data_gas, parent_consumed_data_gas)
        )

    @classmethod
    def get_min_excess_data_gas_for_data_gas_price(cls, data_gas_price: int) -> int:
        """
        Gets the minimum required excess data gas value to get a given data gas cost in a block
        """
        current_excess_data_gas = 0
        current_data_gas_price = 1
        while current_data_gas_price < data_gas_price:
            current_excess_data_gas += Spec.DATA_GAS_PER_BLOB
            current_data_gas_price = Spec.get_data_gasprice(
                excess_data_gas=current_excess_data_gas
            )
        return current_excess_data_gas

    @classmethod
    def get_min_excess_data_blobs_for_data_gas_price(cls, data_gas_price: int) -> int:
        """
        Gets the minimum required excess data blobs to get a given data gas cost in a block
        """
        return (
            cls.get_min_excess_data_gas_for_data_gas_price(data_gas_price)
            // Spec.DATA_GAS_PER_BLOB
        )