ethereum.tangerine_whistle.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.

30
@dataclass
class State:

_main_trie

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

_storage_tries

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

_snapshots

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

close_state

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

def 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

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.

def begin_transaction(​state: State​) -> None:
60
    """
61
    Start a state transaction.
62
63
    Transactions are entirely implicit and can be nested. It is not possible to
64
    calculate the state root during a transaction.
65
66
    Parameters
67
    ----------
68
    state : State
69
        The state.
70
    """
71
    state._snapshots.append(
72
        (
73
            copy_trie(state._main_trie),
74
            {k: copy_trie(t) for (k, t) in state._storage_tries.items()},
75
        )
76
    )

commit_transaction

Commit a state transaction.

Parameters

state : State The state.

def commit_transaction(​state: State​) -> None:
80
    """
81
    Commit a state transaction.
82
83
    Parameters
84
    ----------
85
    state : State
86
        The state.
87
    """
88
    state._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.

def rollback_transaction(​state: State​) -> None:
92
    """
93
    Rollback a state transaction, resetting the state to the point when the
94
    corresponding `start_transaction()` call was made.
95
96
    Parameters
97
    ----------
98
    state : State
99
        The state.
100
    """
101
    state._main_trie, state._storage_tries = state._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:
105
    """
106
    Get the `Account` object at an address. Returns `EMPTY_ACCOUNT` if there
107
    is no account at the address.
108
109
    Use `get_account_optional()` if you care about the difference between a
110
    non-existent account and `EMPTY_ACCOUNT`.
111
112
    Parameters
113
    ----------
114
    state: `State`
115
        The state
116
    address : `Address`
117
        Address to lookup.
118
119
    Returns
120
    -------
121
    account : `Account`
122
        Account at address.
123
    """
124
    account = get_account_optional(state, address)
125
    if isinstance(account, Account):
126
        return account
127
    else:
128
        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]:
132
    """
133
    Get the `Account` object at an address. Returns `None` (rather than
134
    `EMPTY_ACCOUNT`) if there is no account at the address.
135
136
    Parameters
137
    ----------
138
    state: `State`
139
        The state
140
    address : `Address`
141
        Address to lookup.
142
143
    Returns
144
    -------
145
    account : `Account`
146
        Account at address.
147
    """
148
    account = trie_get(state._main_trie, address)
149
    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:
155
    """
156
    Set the `Account` object at an address. Setting to `None` deletes
157
    the account (but not its storage, see `destroy_account()`).
158
159
    Parameters
160
    ----------
161
    state: `State`
162
        The state
163
    address : `Address`
164
        Address to set.
165
    account : `Account`
166
        Account to set at address.
167
    """
168
    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:
172
    """
173
    Completely remove the account at `address` and all of its storage.
174
175
    This function is made available exclusively for the `SELFDESTRUCT`
176
    opcode. It is expected that `SELFDESTRUCT` will be disabled in a future
177
    hardfork and this function will be removed.
178
179
    Parameters
180
    ----------
181
    state: `State`
182
        The state
183
    address : `Address`
184
        Address of account to destroy.
185
    """
186
    destroy_storage(state, address)
187
    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:
191
    """
192
    Completely remove the storage at `address`.
193
194
    Parameters
195
    ----------
196
    state: `State`
197
        The state
198
    address : `Address`
199
        Address of account whose storage is to be deleted.
200
    """
201
    if address in state._storage_tries:
202
        del state._storage_tries[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: Bytes​) -> U256:
206
    """
207
    Get a value at a storage key on an account. Returns `U256(0)` if the
208
    storage key has not been set previously.
209
210
    Parameters
211
    ----------
212
    state: `State`
213
        The state
214
    address : `Address`
215
        Address of the account.
216
    key : `Bytes`
217
        Key to lookup.
218
219
    Returns
220
    -------
221
    value : `U256`
222
        Value at the key.
223
    """
224
    trie = state._storage_tries.get(address)
225
    if trie is None:
226
        return U256(0)
227
228
    value = trie_get(trie, key)
229
230
    assert isinstance(value, U256)
231
    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: Bytes, ​​value: U256​) -> None:
237
    """
238
    Set a value at a storage key on an account. Setting to `U256(0)` deletes
239
    the key.
240
241
    Parameters
242
    ----------
243
    state: `State`
244
        The state
245
    address : `Address`
246
        Address of the account.
247
    key : `Bytes`
248
        Key to set.
249
    value : `U256`
250
        Value to set at the key.
251
    """
252
    assert trie_get(state._main_trie, address) is not None
253
254
    trie = state._storage_tries.get(address)
255
    if trie is None:
256
        trie = Trie(secured=True, default=U256(0))
257
        state._storage_tries[address] = trie
258
    trie_set(trie, key, value)
259
    if trie._data == {}:
260
        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:
264
    """
265
    Calculate the storage root of an account.
266
267
    Parameters
268
    ----------
269
    state:
270
        The state
271
    address :
272
        Address of the account.
273
274
    Returns
275
    -------
276
    root : `Root`
277
        Storage root of the account.
278
    """
279
    assert not state._snapshots
280
    if address in state._storage_tries:
281
        return root(state._storage_tries[address])
282
    else:
283
        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:
287
    """
288
    Calculate the state root.
289
290
    Parameters
291
    ----------
292
    state:
293
        The current state.
294
295
    Returns
296
    -------
297
    root : `Root`
298
        The state root.
299
    """
300
    assert not state._snapshots
301
302
    def get_storage_root(address: Address) -> Root:
303
        return storage_root(state, address)
304
305
    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:
309
    """
310
    Checks if an account exists in the state trie
311
312
    Parameters
313
    ----------
314
    state:
315
        The state
316
    address:
317
        Address of the account that needs to be checked.
318
319
    Returns
320
    -------
321
    account_exists : `bool`
322
        True if account exists in the state trie, False otherwise
323
    """
324
    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 if an account has non zero nonce or non empty code, False otherwise.

def account_has_code_or_nonce(​state: State, ​​address: Address​) -> bool:
328
    """
329
    Checks if an account has non zero nonce or non empty code
330
331
    Parameters
332
    ----------
333
    state:
334
        The state
335
    address:
336
        Address of the account that needs to be checked.
337
338
    Returns
339
    -------
340
    has_code_or_nonce : `bool`
341
        True if if an account has non zero nonce or non empty code,
342
        False otherwise.
343
    """
344
    account = get_account(state, address)
345
    return account.nonce != Uint(0) or account.code != b""

modify_state

Modify an Account in the State.

def modify_state(​state: State, ​​address: Address, ​​f: Callable[[Account], None]​) -> None:
351
    """
352
    Modify an `Account` in the `State`.
353
    """
354
    set_account(state, address, modify(get_account(state, address), f))

move_ether

Move funds between accounts.

def move_ether(​state: State, ​​sender_address: Address, ​​recipient_address: Address, ​​amount: U256​) -> None:
363
    """
364
    Move funds between accounts.
365
    """
366
367
    def reduce_sender_balance(sender: Account) -> None:
368
        if sender.balance < amount:
369
            raise AssertionError
370
        sender.balance -= amount
371
372
    def increase_recipient_balance(recipient: Account) -> None:
373
        recipient.balance += amount
374
375
    modify_state(state, sender_address, reduce_sender_balance)
376
    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:
380
    """
381
    Sets the balance of an account.
382
383
    Parameters
384
    ----------
385
    state:
386
        The current state.
387
388
    address:
389
        Address of the account whose nonce needs to be incremented.
390
391
    amount:
392
        The amount that needs to set in balance.
393
    """
394
395
    def set_balance(account: Account) -> None:
396
        account.balance = amount
397
398
    modify_state(state, address, set_balance)

touch_account

Initializes an account to state.

Parameters

state: The current state.

address: The address of the account that need to initialised.

def touch_account(​state: State, ​​address: Address​) -> None:
402
    """
403
    Initializes an account to state.
404
405
    Parameters
406
    ----------
407
    state:
408
        The current state.
409
410
    address:
411
        The address of the account that need to initialised.
412
    """
413
    if not account_exists(state, address):
414
        set_account(state, address, EMPTY_ACCOUNT)

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:
418
    """
419
    Increments the nonce of an account.
420
421
    Parameters
422
    ----------
423
    state:
424
        The current state.
425
426
    address:
427
        Address of the account whose nonce needs to be incremented.
428
    """
429
430
    def increase_nonce(sender: Account) -> None:
431
        sender.nonce += Uint(1)
432
433
    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:
437
    """
438
    Sets Account code.
439
440
    Parameters
441
    ----------
442
    state:
443
        The current state.
444
445
    address:
446
        Address of the account whose code needs to be update.
447
448
    code:
449
        The bytecode that needs to be set.
450
    """
451
452
    def write_code(sender: Account) -> None:
453
        sender.code = code
454
455
    modify_state(state, address, write_code)

create_ether

Add newly created ether to an account.

Parameters

state: The current state. address: Address of the account to which ether is added. amount: The amount of ether to be added to the account of interest.

def create_ether(​state: State, ​​address: Address, ​​amount: U256​) -> None:
459
    """
460
    Add newly created ether to an account.
461
462
    Parameters
463
    ----------
464
    state:
465
        The current state.
466
    address:
467
        Address of the account to which ether is added.
468
    amount:
469
        The amount of ether to be added to the account of interest.
470
    """
471
472
    def increase_balance(account: Account) -> None:
473
        account.balance += amount
474
475
    modify_state(state, address, increase_balance)