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

account_exists_and_is_empty

Checks if an account exists and has zero nonce, empty code and zero balance.

Parameters

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

Returns

exists_and_is_empty : bool True if an account exists and has zero nonce, empty code and zero balance, False otherwise.

def account_exists_and_is_empty(​state: State, ​​address: Address​) -> bool:
429
    """
430
    Checks if an account exists and has zero nonce, empty code and zero
431
    balance.
432
433
    Parameters
434
    ----------
435
    state:
436
        The state
437
    address:
438
        Address of the account that needs to be checked.
439
440
    Returns
441
    -------
442
    exists_and_is_empty : `bool`
443
        True if an account exists and has zero nonce, empty code and zero
444
        balance, False otherwise.
445
    """
446
    account = get_account_optional(state, address)
447
    return (
448
        account is not None
449
        and account.nonce == Uint(0)
450
        and account.code == b""
451
        and account.balance == 0
452
    )

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:
456
    """
457
    Check whether is an account is both in the state and non empty.
458
459
    Parameters
460
    ----------
461
    state:
462
        The state
463
    address:
464
        Address of the account that needs to be checked.
465
466
    Returns
467
    -------
468
    is_alive : `bool`
469
        True if the account is alive.
470
    """
471
    account = get_account_optional(state, address)
472
    return account is not None and account != EMPTY_ACCOUNT

modify_state

Modify an Account in the State.

def modify_state(​state: State, ​​address: Address, ​​f: Callable[[Account], None]​) -> None:
478
    """
479
    Modify an `Account` in the `State`.
480
    """
481
    set_account(state, address, modify(get_account(state, address), f))
482
    if account_exists_and_is_empty(state, address):
483
        destroy_account(state, address)

move_ether

Move funds between accounts.

def move_ether(​state: State, ​​sender_address: Address, ​​recipient_address: Address, ​​amount: U256​) -> None:
492
    """
493
    Move funds between accounts.
494
    """
495
496
    def reduce_sender_balance(sender: Account) -> None:
497
        if sender.balance < amount:
498
            raise AssertionError
499
        sender.balance -= amount
500
501
    def increase_recipient_balance(recipient: Account) -> None:
502
        recipient.balance += amount
503
504
    modify_state(state, sender_address, reduce_sender_balance)
505
    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:
509
    """
510
    Sets the balance of an account.
511
512
    Parameters
513
    ----------
514
    state:
515
        The current state.
516
517
    address:
518
        Address of the account whose nonce needs to be incremented.
519
520
    amount:
521
        The amount that needs to set in balance.
522
    """
523
524
    def set_balance(account: Account) -> None:
525
        account.balance = amount
526
527
    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:
531
    """
532
    Increments the nonce of an account.
533
534
    Parameters
535
    ----------
536
    state:
537
        The current state.
538
539
    address:
540
        Address of the account whose nonce needs to be incremented.
541
    """
542
543
    def increase_nonce(sender: Account) -> None:
544
        sender.nonce += Uint(1)
545
546
    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:
550
    """
551
    Sets Account code.
552
553
    Parameters
554
    ----------
555
    state:
556
        The current state.
557
558
    address:
559
        Address of the account whose code needs to be update.
560
561
    code:
562
        The bytecode that needs to be set.
563
    """
564
565
    def write_code(sender: Account) -> None:
566
        sender.code = code
567
568
    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:
572
    """
573
    Get the original value in a storage slot i.e. the value before the current
574
    transaction began. This function reads the value from the snapshots taken
575
    before executing the transaction.
576
577
    Parameters
578
    ----------
579
    state:
580
        The current state.
581
    address:
582
        Address of the account to read the value from.
583
    key:
584
        Key of the storage slot.
585
    """
586
    # In the transaction where an account is created, its preexisting storage
587
    # is ignored.
588
    if address in state.created_accounts:
589
        return U256(0)
590
591
    _, original_trie = state._snapshots[0]
592
    original_account_trie = original_trie.get(address)
593
594
    if original_account_trie is None:
595
        original_value = U256(0)
596
    else:
597
        original_value = trie_get(original_account_trie, key)
598
599
    assert isinstance(original_value, U256)
600
601
    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:
607
    """
608
    Get a value at a storage key on an account from transient storage.
609
    Returns `U256(0)` if the storage key has not been set previously.
610
    Parameters
611
    ----------
612
    transient_storage: `TransientStorage`
613
        The transient storage
614
    address : `Address`
615
        Address of the account.
616
    key : `Bytes`
617
        Key to lookup.
618
    Returns
619
    -------
620
    value : `U256`
621
        Value at the key.
622
    """
623
    trie = transient_storage._tries.get(address)
624
    if trie is None:
625
        return U256(0)
626
627
    value = trie_get(trie, key)
628
629
    assert isinstance(value, U256)
630
    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:
639
    """
640
    Set a value at a storage key on an account. Setting to `U256(0)` deletes
641
    the key.
642
    Parameters
643
    ----------
644
    transient_storage: `TransientStorage`
645
        The transient storage
646
    address : `Address`
647
        Address of the account.
648
    key : `Bytes`
649
        Key to set.
650
    value : `U256`
651
        Value to set at the key.
652
    """
653
    trie = transient_storage._tries.get(address)
654
    if trie is None:
655
        trie = Trie(secured=True, default=U256(0))
656
        transient_storage._tries[address] = trie
657
    trie_set(trie, key, value)
658
    if trie._data == {}:
659
        del transient_storage._tries[address]