ethereum.tangerine_whistle.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 modify_state(
348    state: State, address: Address, f: Callable[[Account], None]
349) -> None:
350    """
351    Modify an `Account` in the `State`.
352    """
353    set_account(state, address, modify(get_account(state, address), f))
354
355
356def move_ether(
357    state: State,
358    sender_address: Address,
359    recipient_address: Address,
360    amount: U256,
361) -> None:
362    """
363    Move funds between accounts.
364    """
365
366    def reduce_sender_balance(sender: Account) -> None:
367        ensure(sender.balance >= amount, AssertionError)
368        sender.balance -= amount
369
370    def increase_recipient_balance(recipient: Account) -> None:
371        recipient.balance += amount
372
373    modify_state(state, sender_address, reduce_sender_balance)
374    modify_state(state, recipient_address, increase_recipient_balance)
375
376
377def set_account_balance(state: State, address: Address, amount: U256) -> None:
378    """
379    Sets the balance of an account.
380
381    Parameters
382    ----------
383    state:
384        The current state.
385
386    address:
387        Address of the account whose nonce needs to be incremented.
388
389    amount:
390        The amount that needs to set in balance.
391    """
392
393    def set_balance(account: Account) -> None:
394        account.balance = amount
395
396    modify_state(state, address, set_balance)
397
398
399def touch_account(state: State, address: Address) -> None:
400    """
401    Initializes an account to state.
402
403    Parameters
404    ----------
405    state:
406        The current state.
407
408    address:
409        The address of the account that need to initialised.
410    """
411    if not account_exists(state, address):
412        set_account(state, address, EMPTY_ACCOUNT)
413
414
415def increment_nonce(state: State, address: Address) -> None:
416    """
417    Increments the nonce of an account.
418
419    Parameters
420    ----------
421    state:
422        The current state.
423
424    address:
425        Address of the account whose nonce needs to be incremented.
426    """
427
428    def increase_nonce(sender: Account) -> None:
429        sender.nonce += 1
430
431    modify_state(state, address, increase_nonce)
432
433
434def set_code(state: State, address: Address, code: Bytes) -> None:
435    """
436    Sets Account code.
437
438    Parameters
439    ----------
440    state:
441        The current state.
442
443    address:
444        Address of the account whose code needs to be update.
445
446    code:
447        The bytecode that needs to be set.
448    """
449
450    def write_code(sender: Account) -> None:
451        sender.code = code
452
453    modify_state(state, address, write_code)
454
455
456def create_ether(state: State, address: Address, amount: U256) -> None:
457    """
458    Add newly created ether to an account.
459
460    Parameters
461    ----------
462    state:
463        The current state.
464    address:
465        Address of the account to which ether is added.
466    amount:
467        The amount of ether to be added to the account of interest.
468    """
469
470    def increase_balance(account: Account) -> None:
471        account.balance += amount
472
473    modify_state(state, address, increase_balance)