> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# World State and State Management

> Every account balance, contract storage slot, and nonce on StableNet lives in the world state — a Merkle Patricia Trie updated atomically with each block.

> The world state is the complete snapshot of every account on StableNet. Every transaction either changes it or leaves it exactly as it was — there is no partial update.

## What the world state contains

Every address on StableNet has five fields:

| Field         | Type      | Description                                                        |
| ------------- | --------- | ------------------------------------------------------------------ |
| `nonce`       | `uint64`  | Number of transactions sent (EOA) or contracts created (contract)  |
| `balance`     | `uint256` | WKRC balance in wei — identical to `WKRC.balanceOf(address)`       |
| `codeHash`    | `bytes32` | Keccak-256 of contract bytecode; `keccak256("")` for EOAs          |
| `storageRoot` | `bytes32` | Root of the account's storage trie                                 |
| `extra`       | `uint64`  | StableNet policy flags (blacklist, authorized) — set by GovCouncil |

Addresses that have never received WKRC or sent a transaction do not exist in the state — there is no "empty account" entry.

## How transactions change state

Each transaction runs against a **snapshot** of the current state. Changes are journaled as they happen. If execution succeeds, the changes are committed. If it reverts, the journal unwinds and the state is identical to before the call.

```text theme={null}
Before tx:  StateDB snapshot created
During tx:  balance / nonce / storage changes journaled in memory
On revert:  journal unwound → state unchanged
On success: changes finalized → new state root computed
```

This applies at every call depth. A top-level transaction that calls contract A, which calls contract B — if B reverts, only B's changes are rolled back. A's changes up to that point are preserved (unless A also reverts).

## Contract storage

Each contract has its own **storage trie** — a separate key-value store keyed by 32-byte slot numbers. Solidity variables map to storage slots according to the [layout rules](https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html).

Reading a slot that was never written returns `bytes32(0)`. Writing `bytes32(0)` to an occupied slot frees it (important for gas refunds).

```solidity theme={null}
// These read from the storage trie
uint256 public counter;          // slot 0
mapping(address => uint256) bal; // slot 1 (keys hashed with slot number)
```

To read contract storage without a transaction, use `eth_getStorageAt`:

```typescript theme={null}
const value = await provider.getStorage(contractAddress, slotIndex);
```

## State roots and block finality

At the end of each block, all pending state changes are committed and a new **state root** is computed from the account trie. This root is embedded in the block header — verifying a block means verifying this root matches the expected post-state.

Because StableNet uses Anzeon WBFT with deterministic finality, the state root in block N is final the moment that block is committed. There is no fork that could produce a different state root for the same block number.

## The `extra` field

StableNet extends the standard Ethereum account structure with an `extra` field managed by GovCouncil:

| Bit         | Meaning           | Effect                                           |
| ----------- | ----------------- | ------------------------------------------------ |
| Blacklisted | Set by GovCouncil | All transfers involving this address are blocked |
| Authorized  | Set by GovCouncil | Exempt from governance gas tip enforcement       |

Your contract cannot read `extra` directly. The EVM enforces it transparently — a transfer to a blacklisted address will revert without your contract doing anything.

## Developer benefits

* Atomic state changes — a transaction either fully applies or has no effect
* Revert is complete — `require()` failures leave state identical to pre-call
* Contract storage is isolated per address — no namespace collisions between contracts
* `eth_getStorageAt` lets you inspect any storage slot without a transaction

## Related

* [Architecture Overview](/en/v0.3/learn/architecture-overview) — how transactions flow through state transitions
* [EVM Compatibility](/en/v0.3/learn/evm-compatibility) — supported opcodes that read and write state
* [Governance Overview](/en/v0.3/learn/governance-overview) — how the `extra` field is managed