ethereum.spurious_dragon.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, 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
 47
 48def close_state(state: State) -> None:
 49    """
 50    Free resources held by the state. Used by optimized implementations to
 51    release file descriptors.
 52    """
 53    del state._main_trie
 54    del state._storage_tries
 55    del state._snapshots
 56
 57
 58def begin_transaction(state: State) -> None:
 59    """
 60    Start a state transaction.
 61
 62    Transactions are entirely implicit and can be nested. It is not possible to
 63    calculate the state root during a transaction.
 64
 65    Parameters
 66    ----------
 67    state : State
 68        The state.
 69    """
 70    state._snapshots.append(
 71        (
 72            copy_trie(state._main_trie),
 73            {k: copy_trie(t) for (k, t) in state._storage_tries.items()},
 74        )
 75    )
 76
 77
 78def commit_transaction(state: State) -> None:
 79    """
 80    Commit a state transaction.
 81
 82    Parameters
 83    ----------
 84    state : State
 85        The state.
 86    """
 87    state._snapshots.pop()
 88
 89
 90def rollback_transaction(state: State) -> None:
 91    """
 92    Rollback a state transaction, resetting the state to the point when the
 93    corresponding `start_transaction()` call was made.
 94
 95    Parameters
 96    ----------
 97    state : State
 98        The state.
 99    """
100    state._main_trie, state._storage_tries = state._snapshots.pop()
101
102
103def get_account(state: State, address: Address) -> Account:
104    """
105    Get the `Account` object at an address. Returns `EMPTY_ACCOUNT` if there
106    is no account at the address.
107
108    Use `get_account_optional()` if you care about the difference between a
109    non-existent account and `EMPTY_ACCOUNT`.
110
111    Parameters
112    ----------
113    state: `State`
114        The state
115    address : `Address`
116        Address to lookup.
117
118    Returns
119    -------
120    account : `Account`
121        Account at address.
122    """
123    account = get_account_optional(state, address)
124    if isinstance(account, Account):
125        return account
126    else:
127        return EMPTY_ACCOUNT
128
129
130def get_account_optional(state: State, address: Address) -> Optional[Account]:
131    """
132    Get the `Account` object at an address. Returns `None` (rather than
133    `EMPTY_ACCOUNT`) if there is no account at the address.
134
135    Parameters
136    ----------
137    state: `State`
138        The state
139    address : `Address`
140        Address to lookup.
141
142    Returns
143    -------
144    account : `Account`
145        Account at address.
146    """
147    account = trie_get(state._main_trie, address)
148    return account
149
150
151def set_account(
152    state: State, address: Address, account: Optional[Account]
153) -> None:
154    """
155    Set the `Account` object at an address. Setting to `None` deletes
156    the account (but not its storage, see `destroy_account()`).
157
158    Parameters
159    ----------
160    state: `State`
161        The state
162    address : `Address`
163        Address to set.
164    account : `Account`
165        Account to set at address.
166    """
167    trie_set(state._main_trie, address, account)
168
169
170def destroy_account(state: State, address: Address) -> None:
171    """
172    Completely remove the account at `address` and all of its storage.
173
174    This function is made available exclusively for the `SELFDESTRUCT`
175    opcode. It is expected that `SELFDESTRUCT` will be disabled in a future
176    hardfork and this function will be removed.
177
178    Parameters
179    ----------
180    state: `State`
181        The state
182    address : `Address`
183        Address of account to destroy.
184    """
185    destroy_storage(state, address)
186    set_account(state, address, None)
187
188
189def destroy_storage(state: State, address: Address) -> None:
190    """
191    Completely remove the storage at `address`.
192
193    Parameters
194    ----------
195    state: `State`
196        The state
197    address : `Address`
198        Address of account whose storage is to be deleted.
199    """
200    if address in state._storage_tries:
201        del state._storage_tries[address]
202
203
204def get_storage(state: State, address: Address, key: Bytes) -> U256:
205    """
206    Get a value at a storage key on an account. Returns `U256(0)` if the
207    storage key has not been set previously.
208
209    Parameters
210    ----------
211    state: `State`
212        The state
213    address : `Address`
214        Address of the account.
215    key : `Bytes`
216        Key to lookup.
217
218    Returns
219    -------
220    value : `U256`
221        Value at the key.
222    """
223    trie = state._storage_tries.get(address)
224    if trie is None:
225        return U256(0)
226
227    value = trie_get(trie, key)
228
229    assert isinstance(value, U256)
230    return value
231
232
233def set_storage(
234    state: State, address: Address, key: Bytes, value: U256
235) -> None:
236    """
237    Set a value at a storage key on an account. Setting to `U256(0)` deletes
238    the key.
239
240    Parameters
241    ----------
242    state: `State`
243        The state
244    address : `Address`
245        Address of the account.
246    key : `Bytes`
247        Key to set.
248    value : `U256`
249        Value to set at the key.
250    """
251    assert trie_get(state._main_trie, address) is not None
252
253    trie = state._storage_tries.get(address)
254    if trie is None:
255        trie = Trie(secured=True, default=U256(0))
256        state._storage_tries[address] = trie
257    trie_set(trie, key, value)
258    if trie._data == {}:
259        del state._storage_tries[address]
260
261
262def storage_root(state: State, address: Address) -> Root:
263    """
264    Calculate the storage root of an account.
265
266    Parameters
267    ----------
268    state:
269        The state
270    address :
271        Address of the account.
272
273    Returns
274    -------
275    root : `Root`
276        Storage root of the account.
277    """
278    assert not state._snapshots
279    if address in state._storage_tries:
280        return root(state._storage_tries[address])
281    else:
282        return EMPTY_TRIE_ROOT
283
284
285def state_root(state: State) -> Root:
286    """
287    Calculate the state root.
288
289    Parameters
290    ----------
291    state:
292        The current state.
293
294    Returns
295    -------
296    root : `Root`
297        The state root.
298    """
299    assert not state._snapshots
300
301    def get_storage_root(address: Address) -> Root:
302        return storage_root(state, address)
303
304    return root(state._main_trie, get_storage_root=get_storage_root)
305
306
307def account_exists(state: State, address: Address) -> bool:
308    """
309    Checks if an account exists in the state trie
310
311    Parameters
312    ----------
313    state:
314        The state
315    address:
316        Address of the account that needs to be checked.
317
318    Returns
319    -------
320    account_exists : `bool`
321        True if account exists in the state trie, False otherwise
322    """
323    return get_account_optional(state, address) is not None
324
325
326def account_has_code_or_nonce(state: State, address: Address) -> bool:
327    """
328    Checks if an account has non zero nonce or non empty code
329
330    Parameters
331    ----------
332    state:
333        The state
334    address:
335        Address of the account that needs to be checked.
336
337    Returns
338    -------
339    has_code_or_nonce : `bool`
340        True if if an account has non zero nonce or non empty code,
341        False otherwise.
342    """
343    account = get_account(state, address)
344    return account.nonce != Uint(0) or account.code != b""
345
346
347def is_account_empty(state: State, address: Address) -> bool:
348    """
349    Checks if an account has zero nonce, empty code and zero balance.
350
351    Parameters
352    ----------
353    state:
354        The state
355    address:
356        Address of the account that needs to be checked.
357
358    Returns
359    -------
360    is_empty : `bool`
361        True if if an account has zero nonce, empty code and zero balance,
362        False otherwise.
363    """
364    account = get_account(state, address)
365    return (
366        account.nonce == Uint(0)
367        and account.code == b""
368        and account.balance == 0
369    )
370
371
372def account_exists_and_is_empty(state: State, address: Address) -> bool:
373    """
374    Checks if an account exists and has zero nonce, empty code and zero
375    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    exists_and_is_empty : `bool`
387        True if an account exists and has zero nonce, empty code and zero
388        balance, False otherwise.
389    """
390    account = get_account_optional(state, address)
391    return (
392        account is not None
393        and account.nonce == Uint(0)
394        and account.code == b""
395        and account.balance == 0
396    )
397
398
399def is_account_alive(state: State, address: Address) -> bool:
400    """
401    Check whether is an account is both in the state and non empty.
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    is_alive : `bool`
413        True if the account is alive.
414    """
415    account = get_account_optional(state, address)
416    if account is None:
417        return False
418    else:
419        return not (
420            account.nonce == Uint(0)
421            and account.code == b""
422            and account.balance == 0
423        )
424
425
426def modify_state(
427    state: State, address: Address, f: Callable[[Account], None]
428) -> None:
429    """
430    Modify an `Account` in the `State`.
431    """
432    set_account(state, address, modify(get_account(state, address), f))
433
434
435def move_ether(
436    state: State,
437    sender_address: Address,
438    recipient_address: Address,
439    amount: U256,
440) -> None:
441    """
442    Move funds between accounts.
443    """
444
445    def reduce_sender_balance(sender: Account) -> None:
446        ensure(sender.balance >= amount, AssertionError)
447        sender.balance -= amount
448
449    def increase_recipient_balance(recipient: Account) -> None:
450        recipient.balance += amount
451
452    modify_state(state, sender_address, reduce_sender_balance)
453    modify_state(state, recipient_address, increase_recipient_balance)
454
455
456def set_account_balance(state: State, address: Address, amount: U256) -> None:
457    """
458    Sets the balance of an account.
459
460    Parameters
461    ----------
462    state:
463        The current state.
464
465    address:
466        Address of the account whose nonce needs to be incremented.
467
468    amount:
469        The amount that needs to set in balance.
470    """
471
472    def set_balance(account: Account) -> None:
473        account.balance = amount
474
475    modify_state(state, address, set_balance)
476
477
478def touch_account(state: State, address: Address) -> None:
479    """
480    Initializes an account to state.
481
482    Parameters
483    ----------
484    state:
485        The current state.
486
487    address:
488        The address of the account that need to initialised.
489    """
490    if not account_exists(state, address):
491        set_account(state, address, EMPTY_ACCOUNT)
492
493
494def increment_nonce(state: State, address: Address) -> None:
495    """
496    Increments the nonce of an account.
497
498    Parameters
499    ----------
500    state:
501        The current state.
502
503    address:
504        Address of the account whose nonce needs to be incremented.
505    """
506
507    def increase_nonce(sender: Account) -> None:
508        sender.nonce += 1
509
510    modify_state(state, address, increase_nonce)
511
512
513def set_code(state: State, address: Address, code: Bytes) -> None:
514    """
515    Sets Account code.
516
517    Parameters
518    ----------
519    state:
520        The current state.
521
522    address:
523        Address of the account whose code needs to be update.
524
525    code:
526        The bytecode that needs to be set.
527    """
528
529    def write_code(sender: Account) -> None:
530        sender.code = code
531
532    modify_state(state, address, write_code)
533
534
535def create_ether(state: State, address: Address, amount: U256) -> None:
536    """
537    Add newly created ether to an account.
538
539    Parameters
540    ----------
541    state:
542        The current state.
543    address:
544        Address of the account to which ether is added.
545    amount:
546        The amount of ether to be added to the account of interest.
547    """
548
549    def increase_balance(account: Account) -> None:
550        account.balance += amount
551
552    modify_state(state, address, increase_balance)