ethereum.muir_glacier.state

  1"""
  2State
  3^^^^^
  4
  5.. contents:: Table of Contents
  6    :backlinks: none
  7    :local:
  8
  9Introduction
 10------------
 11
 12The state contains all information that is preserved between transactions.
 13
 14It consists of a main account trie and storage tries for each contract.
 15
 16There is a distinction between an account that does not exist and
 17`EMPTY_ACCOUNT`.
 18"""
 19from dataclasses import dataclass, field
 20from typing import Callable, Dict, List, Optional, Set, Tuple
 21
 22from ethereum.base_types import U256, Bytes, Uint, modify
 23from ethereum.utils.ensure import ensure
 24
 25from .fork_types import EMPTY_ACCOUNT, Account, Address, Root
 26from .trie import EMPTY_TRIE_ROOT, Trie, copy_trie, root, trie_get, trie_set
 27
 28
 29@dataclass
 30class State:
 31    """
 32    Contains all information that is preserved between transactions.
 33    """
 34
 35    _main_trie: Trie[Address, Optional[Account]] = field(
 36        default_factory=lambda: Trie(secured=True, default=None)
 37    )
 38    _storage_tries: Dict[Address, Trie[Bytes, U256]] = field(
 39        default_factory=dict
 40    )
 41    _snapshots: List[
 42        Tuple[
 43            Trie[Address, Optional[Account]], Dict[Address, Trie[Bytes, U256]]
 44        ]
 45    ] = field(default_factory=list)
 46    _created_accounts: Set[Address] = field(default_factory=set)
 47
 48
 49def close_state(state: State) -> None:
 50    """
 51    Free resources held by the state. Used by optimized implementations to
 52    release file descriptors.
 53    """
 54    del state._main_trie
 55    del state._storage_tries
 56    del state._snapshots
 57    del state._created_accounts
 58
 59
 60def begin_transaction(state: State) -> None:
 61    """
 62    Start a state transaction.
 63
 64    Transactions are entirely implicit and can be nested. It is not possible to
 65    calculate the state root during a transaction.
 66
 67    Parameters
 68    ----------
 69    state : State
 70        The state.
 71    """
 72    state._snapshots.append(
 73        (
 74            copy_trie(state._main_trie),
 75            {k: copy_trie(t) for (k, t) in state._storage_tries.items()},
 76        )
 77    )
 78
 79
 80def commit_transaction(state: State) -> None:
 81    """
 82    Commit a state transaction.
 83
 84    Parameters
 85    ----------
 86    state : State
 87        The state.
 88    """
 89    state._snapshots.pop()
 90    if not state._snapshots:
 91        state._created_accounts.clear()
 92
 93
 94def rollback_transaction(state: State) -> None:
 95    """
 96    Rollback a state transaction, resetting the state to the point when the
 97    corresponding `start_transaction()` call was made.
 98
 99    Parameters
100    ----------
101    state : State
102        The state.
103    """
104    state._main_trie, state._storage_tries = state._snapshots.pop()
105    if not state._snapshots:
106        state._created_accounts.clear()
107
108
109def get_account(state: State, address: Address) -> Account:
110    """
111    Get the `Account` object at an address. Returns `EMPTY_ACCOUNT` if there
112    is no account at the address.
113
114    Use `get_account_optional()` if you care about the difference between a
115    non-existent account and `EMPTY_ACCOUNT`.
116
117    Parameters
118    ----------
119    state: `State`
120        The state
121    address : `Address`
122        Address to lookup.
123
124    Returns
125    -------
126    account : `Account`
127        Account at address.
128    """
129    account = get_account_optional(state, address)
130    if isinstance(account, Account):
131        return account
132    else:
133        return EMPTY_ACCOUNT
134
135
136def get_account_optional(state: State, address: Address) -> Optional[Account]:
137    """
138    Get the `Account` object at an address. Returns `None` (rather than
139    `EMPTY_ACCOUNT`) if there is no account at the address.
140
141    Parameters
142    ----------
143    state: `State`
144        The state
145    address : `Address`
146        Address to lookup.
147
148    Returns
149    -------
150    account : `Account`
151        Account at address.
152    """
153    account = trie_get(state._main_trie, address)
154    return account
155
156
157def set_account(
158    state: State, address: Address, account: Optional[Account]
159) -> None:
160    """
161    Set the `Account` object at an address. Setting to `None` deletes
162    the account (but not its storage, see `destroy_account()`).
163
164    Parameters
165    ----------
166    state: `State`
167        The state
168    address : `Address`
169        Address to set.
170    account : `Account`
171        Account to set at address.
172    """
173    trie_set(state._main_trie, address, account)
174
175
176def destroy_account(state: State, address: Address) -> None:
177    """
178    Completely remove the account at `address` and all of its storage.
179
180    This function is made available exclusively for the `SELFDESTRUCT`
181    opcode. It is expected that `SELFDESTRUCT` will be disabled in a future
182    hardfork and this function will be removed.
183
184    Parameters
185    ----------
186    state: `State`
187        The state
188    address : `Address`
189        Address of account to destroy.
190    """
191    destroy_storage(state, address)
192    set_account(state, address, None)
193
194
195def destroy_storage(state: State, address: Address) -> None:
196    """
197    Completely remove the storage at `address`.
198
199    Parameters
200    ----------
201    state: `State`
202        The state
203    address : `Address`
204        Address of account whose storage is to be deleted.
205    """
206    if address in state._storage_tries:
207        del state._storage_tries[address]
208
209
210def mark_account_created(state: State, address: Address) -> None:
211    """
212    Mark an account as having been created in the current transaction.
213    This information is used by `get_storage_original()` to handle an obscure
214    edgecase.
215
216    The marker is not removed even if the account creation reverts. Since the
217    account cannot have had code prior to its creation and can't call
218    `get_storage_original()`, this is harmless.
219
220    Parameters
221    ----------
222    state: `State`
223        The state
224    address : `Address`
225        Address of the account that has been created.
226    """
227    state._created_accounts.add(address)
228
229
230def get_storage(state: State, address: Address, key: Bytes) -> U256:
231    """
232    Get a value at a storage key on an account. Returns `U256(0)` if the
233    storage key has not been set previously.
234
235    Parameters
236    ----------
237    state: `State`
238        The state
239    address : `Address`
240        Address of the account.
241    key : `Bytes`
242        Key to lookup.
243
244    Returns
245    -------
246    value : `U256`
247        Value at the key.
248    """
249    trie = state._storage_tries.get(address)
250    if trie is None:
251        return U256(0)
252
253    value = trie_get(trie, key)
254
255    assert isinstance(value, U256)
256    return value
257
258
259def set_storage(
260    state: State, address: Address, key: Bytes, value: U256
261) -> None:
262    """
263    Set a value at a storage key on an account. Setting to `U256(0)` deletes
264    the key.
265
266    Parameters
267    ----------
268    state: `State`
269        The state
270    address : `Address`
271        Address of the account.
272    key : `Bytes`
273        Key to set.
274    value : `U256`
275        Value to set at the key.
276    """
277    assert trie_get(state._main_trie, address) is not None
278
279    trie = state._storage_tries.get(address)
280    if trie is None:
281        trie = Trie(secured=True, default=U256(0))
282        state._storage_tries[address] = trie
283    trie_set(trie, key, value)
284    if trie._data == {}:
285        del state._storage_tries[address]
286
287
288def storage_root(state: State, address: Address) -> Root:
289    """
290    Calculate the storage root of an account.
291
292    Parameters
293    ----------
294    state:
295        The state
296    address :
297        Address of the account.
298
299    Returns
300    -------
301    root : `Root`
302        Storage root of the account.
303    """
304    assert not state._snapshots
305    if address in state._storage_tries:
306        return root(state._storage_tries[address])
307    else:
308        return EMPTY_TRIE_ROOT
309
310
311def state_root(state: State) -> Root:
312    """
313    Calculate the state root.
314
315    Parameters
316    ----------
317    state:
318        The current state.
319
320    Returns
321    -------
322    root : `Root`
323        The state root.
324    """
325    assert not state._snapshots
326
327    def get_storage_root(address: Address) -> Root:
328        return storage_root(state, address)
329
330    return root(state._main_trie, get_storage_root=get_storage_root)
331
332
333def account_exists(state: State, address: Address) -> bool:
334    """
335    Checks if an account exists in the state trie
336
337    Parameters
338    ----------
339    state:
340        The state
341    address:
342        Address of the account that needs to be checked.
343
344    Returns
345    -------
346    account_exists : `bool`
347        True if account exists in the state trie, False otherwise
348    """
349    return get_account_optional(state, address) is not None
350
351
352def account_has_code_or_nonce(state: State, address: Address) -> bool:
353    """
354    Checks if an account has non zero nonce or non empty code
355
356    Parameters
357    ----------
358    state:
359        The state
360    address:
361        Address of the account that needs to be checked.
362
363    Returns
364    -------
365    has_code_or_nonce : `bool`
366        True if if an account has non zero nonce or non empty code,
367        False otherwise.
368    """
369    account = get_account(state, address)
370    return account.nonce != Uint(0) or account.code != b""
371
372
373def is_account_empty(state: State, address: Address) -> bool:
374    """
375    Checks if an account has zero nonce, empty code and zero balance.
376
377    Parameters
378    ----------
379    state:
380        The state
381    address:
382        Address of the account that needs to be checked.
383
384    Returns
385    -------
386    is_empty : `bool`
387        True if if an account has zero nonce, empty code and zero balance,
388        False otherwise.
389    """
390    account = get_account(state, address)
391    return (
392        account.nonce == Uint(0)
393        and account.code == b""
394        and account.balance == 0
395    )
396
397
398def account_exists_and_is_empty(state: State, address: Address) -> bool:
399    """
400    Checks if an account exists and has zero nonce, empty code and zero
401    balance.
402
403    Parameters
404    ----------
405    state:
406        The state
407    address:
408        Address of the account that needs to be checked.
409
410    Returns
411    -------
412    exists_and_is_empty : `bool`
413        True if an account exists and has zero nonce, empty code and zero
414        balance, False otherwise.
415    """
416    account = get_account_optional(state, address)
417    return (
418        account is not None
419        and account.nonce == Uint(0)
420        and account.code == b""
421        and account.balance == 0
422    )
423
424
425def is_account_alive(state: State, address: Address) -> bool:
426    """
427    Check whether is an account is both in the state and non empty.
428
429    Parameters
430    ----------
431    state:
432        The state
433    address:
434        Address of the account that needs to be checked.
435
436    Returns
437    -------
438    is_alive : `bool`
439        True if the account is alive.
440    """
441    account = get_account_optional(state, address)
442    if account is None:
443        return False
444    else:
445        return not (
446            account.nonce == Uint(0)
447            and account.code == b""
448            and account.balance == 0
449        )
450
451
452def modify_state(
453    state: State, address: Address, f: Callable[[Account], None]
454) -> None:
455    """
456    Modify an `Account` in the `State`.
457    """
458    set_account(state, address, modify(get_account(state, address), f))
459
460
461def move_ether(
462    state: State,
463    sender_address: Address,
464    recipient_address: Address,
465    amount: U256,
466) -> None:
467    """
468    Move funds between accounts.
469    """
470
471    def reduce_sender_balance(sender: Account) -> None:
472        ensure(sender.balance >= amount, AssertionError)
473        sender.balance -= amount
474
475    def increase_recipient_balance(recipient: Account) -> None:
476        recipient.balance += amount
477
478    modify_state(state, sender_address, reduce_sender_balance)
479    modify_state(state, recipient_address, increase_recipient_balance)
480
481
482def set_account_balance(state: State, address: Address, amount: U256) -> None:
483    """
484    Sets the balance of an account.
485
486    Parameters
487    ----------
488    state:
489        The current state.
490
491    address:
492        Address of the account whose nonce needs to be incremented.
493
494    amount:
495        The amount that needs to set in balance.
496    """
497
498    def set_balance(account: Account) -> None:
499        account.balance = amount
500
501    modify_state(state, address, set_balance)
502
503
504def touch_account(state: State, address: Address) -> None:
505    """
506    Initializes an account to state.
507
508    Parameters
509    ----------
510    state:
511        The current state.
512
513    address:
514        The address of the account that need to initialised.
515    """
516    if not account_exists(state, address):
517        set_account(state, address, EMPTY_ACCOUNT)
518
519
520def increment_nonce(state: State, address: Address) -> None:
521    """
522    Increments the nonce of an account.
523
524    Parameters
525    ----------
526    state:
527        The current state.
528
529    address:
530        Address of the account whose nonce needs to be incremented.
531    """
532
533    def increase_nonce(sender: Account) -> None:
534        sender.nonce += 1
535
536    modify_state(state, address, increase_nonce)
537
538
539def set_code(state: State, address: Address, code: Bytes) -> None:
540    """
541    Sets Account code.
542
543    Parameters
544    ----------
545    state:
546        The current state.
547
548    address:
549        Address of the account whose code needs to be update.
550
551    code:
552        The bytecode that needs to be set.
553    """
554
555    def write_code(sender: Account) -> None:
556        sender.code = code
557
558    modify_state(state, address, write_code)
559
560
561def create_ether(state: State, address: Address, amount: U256) -> None:
562    """
563    Add newly created ether to an account.
564
565    Parameters
566    ----------
567    state:
568        The current state.
569    address:
570        Address of the account to which ether is added.
571    amount:
572        The amount of ether to be added to the account of interest.
573    """
574
575    def increase_balance(account: Account) -> None:
576        account.balance += amount
577
578    modify_state(state, address, increase_balance)
579
580
581def get_storage_original(state: State, address: Address, key: Bytes) -> U256:
582    """
583    Get the original value in a storage slot i.e. the value before the current
584    transaction began. This function reads the value from the snapshots taken
585    before executing the transaction.
586
587    Parameters
588    ----------
589    state:
590        The current state.
591    address:
592        Address of the account to read the value from.
593    key:
594        Key of the storage slot.
595    """
596    # In the transaction where an account is created, its preexisting storage
597    # is ignored.
598    if address in state._created_accounts:
599        return U256(0)
600
601    _, original_trie = state._snapshots[0]
602    original_account_trie = original_trie.get(address)
603
604    if original_account_trie is None:
605        original_value = U256(0)
606    else:
607        original_value = trie_get(original_account_trie, key)
608
609    assert isinstance(original_value, U256)
610
611    return original_value