ethereum.cancun.stateethereum.prague.state

State ^^^^^

.. contents:: Table of Contents :backlinks: none :local:

Introduction

The state contains all information that is preserved between transactions.

It consists of a main account trie and storage tries for each contract.

There is a distinction between an account that does not exist and EMPTY_ACCOUNT.

State

Contains all information that is preserved between transactions.

31
@dataclass
class State:

_main_trie

37
    _main_trie: Trie[Address, Optional[Account]] = field(
38
        default_factory=lambda: Trie(secured=True, default=None)
39
    )

_storage_tries

40
    _storage_tries: Dict[Address, Trie[Bytes32, U256]] = field(
41
        default_factory=dict
42
    )

_snapshots

43
    _snapshots: List[
44
        Tuple[
45
            Trie[Address, Optional[Account]],
46
            Dict[Address, Trie[Bytes32, U256]],
47
        ]
48
    ] = field(default_factory=list)

created_accounts

49
    created_accounts: Set[Address] = field(default_factory=set)

TransientStorage

Contains all information that is preserved between message calls within a transaction.

52
@dataclass
class TransientStorage:

_tries

59
    _tries: Dict[Address, Trie[Bytes32, U256]] = field(default_factory=dict)

_snapshots

60
    _snapshots: List[Dict[Address, Trie[Bytes32, U256]]] = field(
61
        default_factory=list
62
    )

close_state

Free resources held by the state. Used by optimized implementations to release file descriptors.

def close_state(​state: State​) -> None:
66
    """
67
    Free resources held by the state. Used by optimized implementations to
68
    release file descriptors.
69
    """
70
    del state._main_trie
71
    del state._storage_tries
72
    del state._snapshots
73
    del state.created_accounts

begin_transaction

Start a state transaction.

Transactions are entirely implicit and can be nested. It is not possible to calculate the state root during a transaction.

Parameters

state : State The state. transient_storage : TransientStorage The transient storage of the transaction.

def begin_transaction(​state: State, ​​transient_storage: TransientStorage​) -> None:
79
    """
80
    Start a state transaction.
81
82
    Transactions are entirely implicit and can be nested. It is not possible to
83
    calculate the state root during a transaction.
84
85
    Parameters
86
    ----------
87
    state : State
88
        The state.
89
    transient_storage : TransientStorage
90
        The transient storage of the transaction.
91
    """
92
    state._snapshots.append(
93
        (
94
            copy_trie(state._main_trie),
95
            {k: copy_trie(t) for (k, t) in state._storage_tries.items()},
96
        )
97
    )
98
    transient_storage._snapshots.append(
99
        {k: copy_trie(t) for (k, t) in transient_storage._tries.items()}
100
    )

commit_transaction

Commit a state transaction.

Parameters

state : State The state. transient_storage : TransientStorage The transient storage of the transaction.

def commit_transaction(​state: State, ​​transient_storage: TransientStorage​) -> None:
106
    """
107
    Commit a state transaction.
108
109
    Parameters
110
    ----------
111
    state : State
112
        The state.
113
    transient_storage : TransientStorage
114
        The transient storage of the transaction.
115
    """
116
    state._snapshots.pop()
117
    if not state._snapshots:
118
        state.created_accounts.clear()
119
120
    transient_storage._snapshots.pop()

rollback_transaction

Rollback a state transaction, resetting the state to the point when the corresponding start_transaction() call was made.

Parameters

state : State The state. transient_storage : TransientStorage The transient storage of the transaction.

def rollback_transaction(​state: State, ​​transient_storage: TransientStorage​) -> None:
126
    """
127
    Rollback a state transaction, resetting the state to the point when the
128
    corresponding `start_transaction()` call was made.
129
130
    Parameters
131
    ----------
132
    state : State
133
        The state.
134
    transient_storage : TransientStorage
135
        The transient storage of the transaction.
136
    """
137
    state._main_trie, state._storage_tries = state._snapshots.pop()
138
    if not state._snapshots:
139
        state.created_accounts.clear()
140
141
    transient_storage._tries = transient_storage._snapshots.pop()

get_account

Get the Account object at an address. Returns EMPTY_ACCOUNT if there is no account at the address.

Use get_account_optional() if you care about the difference between a non-existent account and EMPTY_ACCOUNT.

Parameters

state: State The state address : Address Address to lookup.

Returns

account : Account Account at address.

def get_account(​state: State, ​​address: Address​) -> Account:
145
    """
146
    Get the `Account` object at an address. Returns `EMPTY_ACCOUNT` if there
147
    is no account at the address.
148
149
    Use `get_account_optional()` if you care about the difference between a
150
    non-existent account and `EMPTY_ACCOUNT`.
151
152
    Parameters
153
    ----------
154
    state: `State`
155
        The state
156
    address : `Address`
157
        Address to lookup.
158
159
    Returns
160
    -------
161
    account : `Account`
162
        Account at address.
163
    """
164
    account = get_account_optional(state, address)
165
    if isinstance(account, Account):
166
        return account
167
    else:
168
        return EMPTY_ACCOUNT

get_account_optional

Get the Account object at an address. Returns None (rather than EMPTY_ACCOUNT) if there is no account at the address.

Parameters

state: State The state address : Address Address to lookup.

Returns

account : Account Account at address.

def get_account_optional(​state: State, ​​address: Address​) -> Optional[Account]:
172
    """
173
    Get the `Account` object at an address. Returns `None` (rather than
174
    `EMPTY_ACCOUNT`) if there is no account at the address.
175
176
    Parameters
177
    ----------
178
    state: `State`
179
        The state
180
    address : `Address`
181
        Address to lookup.
182
183
    Returns
184
    -------
185
    account : `Account`
186
        Account at address.
187
    """
188
    account = trie_get(state._main_trie, address)
189
    return account

set_account

Set the Account object at an address. Setting to None deletes the account (but not its storage, see destroy_account()).

Parameters

state: State The state address : Address Address to set. account : Account Account to set at address.

def set_account(​state: State, ​​address: Address, ​​account: Optional[Account]​) -> None:
195
    """
196
    Set the `Account` object at an address. Setting to `None` deletes
197
    the account (but not its storage, see `destroy_account()`).
198
199
    Parameters
200
    ----------
201
    state: `State`
202
        The state
203
    address : `Address`
204
        Address to set.
205
    account : `Account`
206
        Account to set at address.
207
    """
208
    trie_set(state._main_trie, address, account)

destroy_account

Completely remove the account at address and all of its storage.

This function is made available exclusively for the SELFDESTRUCT opcode. It is expected that SELFDESTRUCT will be disabled in a future hardfork and this function will be removed.

Parameters

state: State The state address : Address Address of account to destroy.

def destroy_account(​state: State, ​​address: Address​) -> None:
212
    """
213
    Completely remove the account at `address` and all of its storage.
214
215
    This function is made available exclusively for the `SELFDESTRUCT`
216
    opcode. It is expected that `SELFDESTRUCT` will be disabled in a future
217
    hardfork and this function will be removed.
218
219
    Parameters
220
    ----------
221
    state: `State`
222
        The state
223
    address : `Address`
224
        Address of account to destroy.
225
    """
226
    destroy_storage(state, address)
227
    set_account(state, address, None)

destroy_storage

Completely remove the storage at address.

Parameters

state: State The state address : Address Address of account whose storage is to be deleted.

def destroy_storage(​state: State, ​​address: Address​) -> None:
231
    """
232
    Completely remove the storage at `address`.
233
234
    Parameters
235
    ----------
236
    state: `State`
237
        The state
238
    address : `Address`
239
        Address of account whose storage is to be deleted.
240
    """
241
    if address in state._storage_tries:
242
        del state._storage_tries[address]

mark_account_created

Mark an account as having been created in the current transaction. This information is used by get_storage_original() to handle an obscure edgecase, and to respect the constraints added to SELFDESTRUCT by EIP-6780.

The marker is not removed even if the account creation reverts. Since the account cannot have had code prior to its creation and can't call get_storage_original(), this is harmless.

Parameters

state: State The state address : Address Address of the account that has been created.

def mark_account_created(​state: State, ​​address: Address​) -> None:
246
    """
247
    Mark an account as having been created in the current transaction.
248
    This information is used by `get_storage_original()` to handle an obscure
249
    edgecase, and to respect the constraints added to SELFDESTRUCT by
250
    EIP-6780.
251
252
    The marker is not removed even if the account creation reverts. Since the
253
    account cannot have had code prior to its creation and can't call
254
    `get_storage_original()`, this is harmless.
255
256
    Parameters
257
    ----------
258
    state: `State`
259
        The state
260
    address : `Address`
261
        Address of the account that has been created.
262
    """
263
    state.created_accounts.add(address)

get_storage

Get a value at a storage key on an account. Returns U256(0) if the storage key has not been set previously.

Parameters

state: State The state address : Address Address of the account. key : Bytes Key to lookup.

Returns

value : U256 Value at the key.

def get_storage(​state: State, ​​address: Address, ​​key: Bytes32​) -> U256:
267
    """
268
    Get a value at a storage key on an account. Returns `U256(0)` if the
269
    storage key has not been set previously.
270
271
    Parameters
272
    ----------
273
    state: `State`
274
        The state
275
    address : `Address`
276
        Address of the account.
277
    key : `Bytes`
278
        Key to lookup.
279
280
    Returns
281
    -------
282
    value : `U256`
283
        Value at the key.
284
    """
285
    trie = state._storage_tries.get(address)
286
    if trie is None:
287
        return U256(0)
288
289
    value = trie_get(trie, key)
290
291
    assert isinstance(value, U256)
292
    return value

set_storage

Set a value at a storage key on an account. Setting to U256(0) deletes the key.

Parameters

state: State The state address : Address Address of the account. key : Bytes Key to set. value : U256 Value to set at the key.

def set_storage(​state: State, ​​address: Address, ​​key: Bytes32, ​​value: U256​) -> None:
298
    """
299
    Set a value at a storage key on an account. Setting to `U256(0)` deletes
300
    the key.
301
302
    Parameters
303
    ----------
304
    state: `State`
305
        The state
306
    address : `Address`
307
        Address of the account.
308
    key : `Bytes`
309
        Key to set.
310
    value : `U256`
311
        Value to set at the key.
312
    """
313
    assert trie_get(state._main_trie, address) is not None
314
315
    trie = state._storage_tries.get(address)
316
    if trie is None:
317
        trie = Trie(secured=True, default=U256(0))
318
        state._storage_tries[address] = trie
319
    trie_set(trie, key, value)
320
    if trie._data == {}:
321
        del state._storage_tries[address]

storage_root

Calculate the storage root of an account.

Parameters

state: The state address : Address of the account.

Returns

root : Root Storage root of the account.

def storage_root(​state: State, ​​address: Address​) -> Root:
325
    """
326
    Calculate the storage root of an account.
327
328
    Parameters
329
    ----------
330
    state:
331
        The state
332
    address :
333
        Address of the account.
334
335
    Returns
336
    -------
337
    root : `Root`
338
        Storage root of the account.
339
    """
340
    assert not state._snapshots
341
    if address in state._storage_tries:
342
        return root(state._storage_tries[address])
343
    else:
344
        return EMPTY_TRIE_ROOT

state_root

Calculate the state root.

Parameters

state: The current state.

Returns

root : Root The state root.

def state_root(​state: State​) -> Root:
348
    """
349
    Calculate the state root.
350
351
    Parameters
352
    ----------
353
    state:
354
        The current state.
355
356
    Returns
357
    -------
358
    root : `Root`
359
        The state root.
360
    """
361
    assert not state._snapshots
362
363
    def get_storage_root(address: Address) -> Root:
364
        return storage_root(state, address)
365
366
    return root(state._main_trie, get_storage_root=get_storage_root)

account_exists

Checks if an account exists in the state trie

Parameters

state: The state address: Address of the account that needs to be checked.

Returns

account_exists : bool True if account exists in the state trie, False otherwise

def account_exists(​state: State, ​​address: Address​) -> bool:
370
    """
371
    Checks if an account exists in the state trie
372
373
    Parameters
374
    ----------
375
    state:
376
        The state
377
    address:
378
        Address of the account that needs to be checked.
379
380
    Returns
381
    -------
382
    account_exists : `bool`
383
        True if account exists in the state trie, False otherwise
384
    """
385
    return get_account_optional(state, address) is not None

account_has_code_or_nonce

Checks if an account has non zero nonce or non empty code

Parameters

state: The state address: Address of the account that needs to be checked.

Returns

has_code_or_nonce : bool True if the account has non zero nonce or non empty code, False otherwise.

def account_has_code_or_nonce(​state: State, ​​address: Address​) -> bool:
389
    """
390
    Checks if an account has non zero nonce or non empty code
391
392
    Parameters
393
    ----------
394
    state:
395
        The state
396
    address:
397
        Address of the account that needs to be checked.
398
399
    Returns
400
    -------
401
    has_code_or_nonce : `bool`
402
        True if the account has non zero nonce or non empty code,
403
        False otherwise.
404
    """
405
    account = get_account(state, address)
406
    return account.nonce != Uint(0) or account.code != b""

account_has_storage

Checks if an account has storage.

Parameters

state: The state address: Address of the account that needs to be checked.

Returns

has_storage : bool True if the account has storage, False otherwise.

def account_has_storage(​state: State, ​​address: Address​) -> bool:
410
    """
411
    Checks if an account has storage.
412
413
    Parameters
414
    ----------
415
    state:
416
        The state
417
    address:
418
        Address of the account that needs to be checked.
419
420
    Returns
421
    -------
422
    has_storage : `bool`
423
        True if the account has storage, False otherwise.
424
    """
425
    return address in state._storage_tries

is_account_alive

Check whether is an account is both in the state and non empty.

Parameters

state: The state address: Address of the account that needs to be checked.

Returns

is_alive : bool True if the account is alive.

def is_account_alive(​state: State, ​​address: Address​) -> bool:
429
    """
430
    Check whether is an account is both in the state and non empty.
431
432
    Parameters
433
    ----------
434
    state:
435
        The state
436
    address:
437
        Address of the account that needs to be checked.
438
439
    Returns
440
    -------
441
    is_alive : `bool`
442
        True if the account is alive.
443
    """
444
    account = get_account_optional(state, address)
445
    return account is not None and account != EMPTY_ACCOUNT

modify_state

Modify an Account in the State. If, after modification, the account exists and has zero nonce, empty code, and zero balance, it is destroyed.

def modify_state(​state: State, ​​address: Address, ​​f: Callable[[Account], None]​) -> None:
451
    """
452
    Modify an `Account` in the `State`. If, after modification, the account
453
    exists and has zero nonce, empty code, and zero balance, it is destroyed.
454
    """
455
    set_account(state, address, modify(get_account(state, address), f))
456
457
    account = get_account_optional(state, address)
458
    account_exists_and_is_empty = (
459
        account is not None
460
        and account.nonce == Uint(0)
461
        and account.code == b""
462
        and account.balance == 0
463
    )
464
465
    if account_exists_and_is_empty:
466
        destroy_account(state, address)

move_ether

Move funds between accounts.

def move_ether(​state: State, ​​sender_address: Address, ​​recipient_address: Address, ​​amount: U256​) -> None:
475
    """
476
    Move funds between accounts.
477
    """
478
479
    def reduce_sender_balance(sender: Account) -> None:
480
        if sender.balance < amount:
481
            raise AssertionError
482
        sender.balance -= amount
483
484
    def increase_recipient_balance(recipient: Account) -> None:
485
        recipient.balance += amount
486
487
    modify_state(state, sender_address, reduce_sender_balance)
488
    modify_state(state, recipient_address, increase_recipient_balance)

set_account_balance

Sets the balance of an account.

Parameters

state: The current state.

address: Address of the account whose nonce needs to be incremented.

amount: The amount that needs to set in balance.

def set_account_balance(​state: State, ​​address: Address, ​​amount: U256​) -> None:
492
    """
493
    Sets the balance of an account.
494
495
    Parameters
496
    ----------
497
    state:
498
        The current state.
499
500
    address:
501
        Address of the account whose nonce needs to be incremented.
502
503
    amount:
504
        The amount that needs to set in balance.
505
    """
506
507
    def set_balance(account: Account) -> None:
508
        account.balance = amount
509
510
    modify_state(state, address, set_balance)

increment_nonce

Increments the nonce of an account.

Parameters

state: The current state.

address: Address of the account whose nonce needs to be incremented.

def increment_nonce(​state: State, ​​address: Address​) -> None:
514
    """
515
    Increments the nonce of an account.
516
517
    Parameters
518
    ----------
519
    state:
520
        The current state.
521
522
    address:
523
        Address of the account whose nonce needs to be incremented.
524
    """
525
526
    def increase_nonce(sender: Account) -> None:
527
        sender.nonce += Uint(1)
528
529
    modify_state(state, address, increase_nonce)

set_code

Sets Account code.

Parameters

state: The current state.

address: Address of the account whose code needs to be update.

code: The bytecode that needs to be set.

def set_code(​state: State, ​​address: Address, ​​code: Bytes​) -> None:
533
    """
534
    Sets Account code.
535
536
    Parameters
537
    ----------
538
    state:
539
        The current state.
540
541
    address:
542
        Address of the account whose code needs to be update.
543
544
    code:
545
        The bytecode that needs to be set.
546
    """
547
548
    def write_code(sender: Account) -> None:
549
        sender.code = code
550
551
    modify_state(state, address, write_code)

get_storage_original

Get the original value in a storage slot i.e. the value before the current transaction began. This function reads the value from the snapshots taken before executing the transaction.

Parameters

state: The current state. address: Address of the account to read the value from. key: Key of the storage slot.

def get_storage_original(​state: State, ​​address: Address, ​​key: Bytes32​) -> U256:
555
    """
556
    Get the original value in a storage slot i.e. the value before the current
557
    transaction began. This function reads the value from the snapshots taken
558
    before executing the transaction.
559
560
    Parameters
561
    ----------
562
    state:
563
        The current state.
564
    address:
565
        Address of the account to read the value from.
566
    key:
567
        Key of the storage slot.
568
    """
569
    # In the transaction where an account is created, its preexisting storage
570
    # is ignored.
571
    if address in state.created_accounts:
572
        return U256(0)
573
574
    _, original_trie = state._snapshots[0]
575
    original_account_trie = original_trie.get(address)
576
577
    if original_account_trie is None:
578
        original_value = U256(0)
579
    else:
580
        original_value = trie_get(original_account_trie, key)
581
582
    assert isinstance(original_value, U256)
583
584
    return original_value

get_transient_storage

Get a value at a storage key on an account from transient storage. Returns U256(0) if the storage key has not been set previously. Parameters

transient_storage: TransientStorage The transient storage address : Address Address of the account. key : Bytes Key to lookup. Returns

value : U256 Value at the key.

def get_transient_storage(​transient_storage: TransientStorage, ​​address: Address, ​​key: Bytes32​) -> U256:
590
    """
591
    Get a value at a storage key on an account from transient storage.
592
    Returns `U256(0)` if the storage key has not been set previously.
593
    Parameters
594
    ----------
595
    transient_storage: `TransientStorage`
596
        The transient storage
597
    address : `Address`
598
        Address of the account.
599
    key : `Bytes`
600
        Key to lookup.
601
    Returns
602
    -------
603
    value : `U256`
604
        Value at the key.
605
    """
606
    trie = transient_storage._tries.get(address)
607
    if trie is None:
608
        return U256(0)
609
610
    value = trie_get(trie, key)
611
612
    assert isinstance(value, U256)
613
    return value

set_transient_storage

Set a value at a storage key on an account. Setting to U256(0) deletes the key. Parameters

transient_storage: TransientStorage The transient storage address : Address Address of the account. key : Bytes Key to set. value : U256 Value to set at the key.

def set_transient_storage(​transient_storage: TransientStorage, ​​address: Address, ​​key: Bytes32, ​​value: U256​) -> None:
622
    """
623
    Set a value at a storage key on an account. Setting to `U256(0)` deletes
624
    the key.
625
    Parameters
626
    ----------
627
    transient_storage: `TransientStorage`
628
        The transient storage
629
    address : `Address`
630
        Address of the account.
631
    key : `Bytes`
632
        Key to set.
633
    value : `U256`
634
        Value to set at the key.
635
    """
636
    trie = transient_storage._tries.get(address)
637
    if trie is None:
638
        trie = Trie(secured=True, default=U256(0))
639
        transient_storage._tries[address] = trie
640
    trie_set(trie, key, value)
641
    if trie._data == {}:
642
        del transient_storage._tries[address]