
In this article, we will use the terms "Events" and "Logs" to refer to the same concept. In Ethereum, one term or the other is preferred depending on the context (for example, "logs" in the EVM and "events" in Solidity). However, since both terms are interdependent and one is a consequence of the other, we will use them interchangeably to refer to the same thing.

## What are they?

In Solidity, events can be considered as an abstraction of the logs that the EVM uses to store information in an indexed data structure known as Bloom Filters[^1]. This structure enables efficient information retrieval, allowing light nodes (those that do not store the entire blockchain history) to query the logs.

## What are they for?

When writing a smart contract in Solidity, it is possible to declare and emit events. The question is, what are events for if we **cannot subscribe to them from a contract** or receive updates from other contracts that emit events?

Events in Solidity have the following syntax:

```solidity
contract MySmartContract {
  event UserRegistered(uint256 userId)
  event WinnerSelected(address indexed winnerAddress)

  function registerUser() public {
    emit UserRegistered(10);
  }

  function selectWinner() public {
    emit WinnerSelected(0x2d3052db3062d60643682b1272d00a6bf4a1f5e6);
  }
}
```

To declare events in Solidity, it is necessary to give them a name and define their parameters. Conventionally, the name of the function that emits the event is used, but reversed. To emit an event, simply call the `emit` function along with the name of the event and the defined parameters. It is important to note that some of the parameters may have the keyword `indexed`, while others may not. We will see the use of this in a later section.

Going back to the question, why do we want to emit events that we cannot subscribe to? The answer is that we want to subscribe to those events from **outside** the network. They are often used to update UI's. It is important to note that a blockchain network is like a closed circuit, and it is not possible to bring data from external sources as if it were an HTTP request, nor is it possible to send data to specific servers. It is true that you cannot subscribe directly to an event, as the network does not send you a notification that something has happened, but simply when an event occurs, the EVM adds that log to the node, which **can then be queried** in various ways.

## How to query them?

In this example, we will use the _[composer](https://composer.alchemy.com/)_ tool from Alchemy. As we know, nodes expose a JSON-RPC endpoint to which we can make POST requests. Specifically, we will use the `eth_getLogs` method to obtain logs belonging to a particular contract that has emitted an event. Initially, it is only mandatory to include the contract address as a parameter, but it is important to add the block range to avoid overloading the node by performing a very extensive search.

For example:

![compose example](/composer.webp)

This will result in something like this:

```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": [
    {
      "address": "0x62a6ef16f4c7605e89f6ebbc38dac89bc7aacd0b",
      "blockHash": "0x6df099a0fecc4d4cfae06b691aba295c7de3fde09ffa527eaa71920bbbe4ba35",
      "blockNumber": "0x81f06f",
      "data": "0x00000000000000000000000033ffcccda2a9f07ab03191ebdf8ec0ad5edc6ac000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000009d3052db3062d60643682b1272d00a6bf4a6f5e6",
      "logIndex": "0x37",
      "removed": false,
      "topics": ["0x5ba0ddd8e72e3c5c274414bd1ef0dec9ae5220e0f6f534d859043e2a52f0319f"],
      "transactionHash": "0xda633d761ae7683cb75de343ef6651daed5f8b78ce9d0e622345c4f392087a7c",
      "transactionIndex": "0x19"
    }
    // ...
  ]
}
```

At first glance, it is not readable, nor does it provide much...We would need other tools to be able to read this code. Later we will see use cases.

## Can we filter them?

Of course! In addition to the block range, you can add _topics_ to the query of the logs. Topics are an array that contains the arguments of the emitted event, but they are added in a specific format. For example, if we want to filter by the `UserRegistered` event, we should add to the topic the hash resulting from applying the keccak256 function to its canonical form[^2] (you can use [this](https://emn178.github.io/online-tools/keccak_256.html) tool to get the value).

```json
// For example, applying the hash function to UserRegistered(uint256) would result in the following hex code
"topics": ["0x6b1da47e6cb6a4952c75fff4300f06caf20aa8269a4a398f315562926c5bed39"]
```

In addition to filtering by event names, we can also filter by the values of their arguments. This is where the `indexed` keyword we saw earlier comes into play. At most, you can have 3 indexed arguments, which means that these values will be added in hexadecimal format to the array of topics. In the case of `UserRegistered`, we couldn't use this functionality, as its argument is not indexed. However, in the `WinnerSelected` event, we could do it. To do this, we should add both the hash and the contract address to the corresponding topic, so the array of topics would be as follows:

```json
"topics":[
  // hash
  "0x1d4c260f1824cd028e6c9e6e31c3a0b94f2513e7a641113ec759d382f9bdd5a1",
  // address
  "0x0000000000000000000000002d3052db3062d60643682b1272d00a6bf4a1f5e6"
]
```

## Use cases

Solidity events are very useful for updating the user interface (UI) of a dApp[^3]. This is because, through libraries like _web3js_ or _ethers_, we can query logs through the provider[^4] and take real-time actions based on the received events. In this way, we can have an UI always updated with the latest information available on the blockchain.

For example:

```javascript
const filter = {
  // Let's assume this is the MySmartContract address
  address: '0x000...123',
  topics: [
    utils.id('WinnerSelected(address)'), // Applies keccak256 hashing function
  ],
};
provider.on(filter, (log, event) => {
  // This will run every time a WinnerSelected event is emitted
});
```

The truth is that filtering logs or making this type of queries to the network is not trivial. If we need to make queries with more complex filters, for example, we would first have to process and store the data in a specific database and then make queries in SQL, Mongo or another tool that is more efficient than querying the blockchain. Luckily, there are some a solution to this problem, and one of them is [The Graph](https://thegraph.com/en/) protocol.

Another use case is at **NFT marketplaces**, where it is necessary to maintain a list of NFTs that are for sale with certain properties (which implies preprocessing the data). To achieve this, we only need to emit events to buy or sell NFTs, listen to them and store the processed data in a separated database, without the need to store this list in the contract, which would be **more expensive**.

To use The Graph, we simply provide the contract address and ABI[^5], and it takes care of constantly querying those events and executing a specific "mapper" function (defined by us) to save them to its node. Then, The Graph node exposes a GraphQL endpoint for us to query the aggregated data in whatever way we desire.

---

### Resources

- [Ethers provider methods](https://docs.ethers.org/v5/api/providers/provider/#Provider--inspection-methods)
- [TheGraph documentation](https://thegraph.com/docs/en/)
- [Playground keccak256](https://emn178.github.io/online-tools/keccak_256.html)
- [Composer](https://composer.alchemy.com/)
- [eth_getlogs documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs)
- [Solidity events docs](https://docs.soliditylang.org/en/v0.4.24/contracts.html#events)

---

[^1]: Bloom Filters: [https://en.wikipedia.org/wiki/Bloom_filter](https://en.wikipedia.org/wiki/Bloom_filter)
[^2]: Canonical form: It means the function name followed by the parameter types. For example `function foo(boolean bar){}` would be `foo(boolean)`
[^3]: DAPP: Decentralized application.
[^4]: Provider: It's an abstraction of the connection to the Ethereum network. If you use web3js or ethers you can configure as provider Infura, Metamask, and Alchemy… among others.
[^5]: ABI: I'ts a JSON file that defines all the variables, functions and events written in a SmartContract


What are they? What are they for? How are the events used in Solidity?

Events in Solidity


In this article, we're going to delve a bit deeper into persistent storage on EVM-compatible blockchains[^1]. In other languages, it's not necessary to know what happens at a low level in order to write efficient code, but in the case of Solidity (which is not quite a high-level language), it is important – though not essential – to know this, because operations cost gas.

Gas is the unit that measures the amount of computational effort required to execute operations on the blockchain. In _Ethereum_, we have a transactional model, and each transaction requires computation to be executed and validated, so a fee (gas) must be paid. In this table fragment, we can see the cost associated with each operation (opcode); we can see that accesses to **Memory** (MLOAD & MSTORE) are much cheaper than accesses to **Storage** (SLOAD & STORE).

| Opcode | Name    | Description            | Extra Info | Gas       |
| ------ | ------- | ---------------------- | ---------- | --------- |
| ...    | ...     | ...                    | -          | ...       |
| 0x51   | MLOAD   | Load word from memory  | -          | 3\*       |
| 0x52   | MSTORE  | Save word to memory    | -          | 3\*       |
| 0x53   | MSTORE8 | Save byte to memory    | -          | 3         |
| 0x54   | SLOAD   | Load word from storage | -          | 800       |
| 0x55   | SSTORE  | Save word to storage   | -          | 20000\*\* |
| ...    | ...     | ...                    | -          | ...       |

Full table at: [https://github.com/crytic/evm-opcodes](https://github.com/crytic/evm-opcodes)

## Memory & Storage

In _Solidity_, there are two types of storage: volatile (Memory), which can be thought of as RAM, and persistent (Storage), which can be thought of as a hard drive.

- **Memory**: Variables defined in the body of functions (whether or not they contain the **memory** keyword) are temporary; they only exist within the _scope_ of that function, and they are deleted when the function execution ends until the next execution, where a new storage space is allocated.

```solidity
contract Foo {
  // State variables
  uint8[] foo;

  function bar(string memory _bar, bool _foo) public {
        // Memory variables
        uint8 baz = 10;
        // Copy of foo, modifications to _baz doesn't affect the foo state
        uint8[] memory _baz = foo;
    }
}
```

- **Storage**: Variables defined outside of functions are considered persistent by default (known as state variables). These variables persist on the blockchain.

```solidity
contract Foo {
  // State variables
  uint8[] foo;

  function bar() public {
      // Reference to foo, modifications to _baz alters the foo state
      uint8[] storage _baz = foo;
    }
}
```

## Storage & SmartContracts

All Smart Contracts running on the EVM have a permanent Storage associated with them, which is part of the blockchain's global state. This _Storage_ can be seen as a list of _key-value_ pairs ordered by their declaration in the Smart Contract, with each element being 32 bytes in size, and a total size of 2^256. While the Storage is large enough to store anything, it initially costs nothing since it's all set to 0. In Ethereum, you pay for everything that's not 0 and for memory expansions.

The **order in which variables are declared is relevant** in Solidity, and they're usually not grouped by domain or other criteria, but by size and type for the EVM's convenience.

Let's take a look at this contract.

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.7;

contract StoragePlayground {
  // State  variables
  uint256 favNumber; // Storage at slot 0
  bool someBool;     // Storage at slot 1

  constructor() {
    favNumber = 5;
    someBool = true;
  }
}
```

To inspect the state of the Storage, we can use the [getStorageAt](https://docs.ethers.io/v5/api/providers/provider/#Provider-getStorageAt) function provided by the provider (in this case, we'll use ethers). We pass it the address of a contract and the memory slot of the data we want to retrieve. This function allows us to examine the contents of the Storage at a specific slot, which can be useful for debugging and analyzing Smart Contracts on the blockchain.

```typescript
// Pseudocode to deploy the smart contract locally
function deployContract() {
  console.log('Deploying StoragePlayground...');
  const contract = await deploy('StoragePlayground', {...});

  for (let slot = 0; slot < 5; slot++) {
    let content = await ethers.provider.getStorageAt(contract.address,slot)
    console.log(`${slot} -> ${content}`)
  }
}
```

This piece of code prints out to the console the first 5 slots in the contract storage.

```bash
0 -> 0x0000000000000000000000000000000000000000000000000000000000000005
1 -> 0x0000000000000000000000000000000000000000000000000000000000000001
2 -> 0x0000000000000000000000000000000000000000000000000000000000000000
3 -> 0x0000000000000000000000000000000000000000000000000000000000000000
4 -> 0x0000000000000000000000000000000000000000000000000000000000000000
```

As expected, the number 5 was stored in position 0 and True in position 1.

If we change the data type of `favNumber` from `uint256` to `uint8` we can see how they share a memory slot:

```bash
0 -> 0x0000000000000000000000000000000000000000000000000000000000000105
1 -> 0x0000000000000000000000000000000000000000000000000000000000000000
2 -> 0x0000000000000000000000000000000000000000000000000000000000000000
3 -> 0x0000000000000000000000000000000000000000000000000000000000000000
4 -> 0x0000000000000000000000000000000000000000000000000000000000000000
```

We can see that the size and type of variables must be taken into account. The [rules](https://docs.soliditylang.org/en/develop/internals/layout_in_storage.html#layout-of-state-variables-in-storage) for declaring variables efficiently are defined in the Solidity documentation.

## Arrays & Mappings

Now let's see some examples using arrays (fixed-size and dynamic) and mappings[^2].

Fixed-size arrays are stored in consecutive positions. We can verify this using the same method as before:

```solidity
contract StoragePlayground {
  // State variables
  uint256 favNumber; // Storage at slot 0
  bool someBool; // Storage at slot 1
  uint256[3] myArray; // Storage slots 2,3 and 4

  constructor() {
     favNumber = 5;
     someBool = true;

     myArray = [10, 20, 30];
  }
}
```

We see that the data stored at slots 2, 3 and 4 are the hexadecimal values of 10, 20 and 30 `(0x00..a, 0x00...14 and 0x00...1e)`

```bash
0 -> 0x0000000000000000000000000000000000000000000000000000000000000005
1 -> 0x0000000000000000000000000000000000000000000000000000000000000001
2 -> 0x000000000000000000000000000000000000000000000000000000000000000a
3 -> 0x0000000000000000000000000000000000000000000000000000000000000014
4 -> 0x000000000000000000000000000000000000000000000000000000000000001e
```

And what about dynamic arrays? How does the EVM know how many slots to reserve between variables?

Well, it doesn't know 😅, and to solve this it uses a hash function _keccak256_, to find a memory position and not overwrite other slots. Let's change the code a bit to add a dynamic array. Replace `uint256[3] myArray` with `uint256[] myArray`. The rest of the code remains the same with the same 3 elements.

```bash
0 -> 0x0000000000000000000000000000000000000000000000000000000000000005
1 -> 0x0000000000000000000000000000000000000000000000000000000000000001
2 -> 0x0000000000000000000000000000000000000000000000000000000000000003
3 -> 0x0000000000000000000000000000000000000000000000000000000000000000
4 -> 0x0000000000000000000000000000000000000000000000000000000000000000
```

We can see that they're gone,but in position 2 we have stored the number 3, which represents the length of the array and gets updated as elements are added. However, the slot where it is stored remains the same, which is slot 2. To calculate the position from which the array data is stored, the function `keccak256(slot-where-the-array-length-is-stored)` is used. Ethers provides us with this function:

We know that it is in slot 2 (0x2 in hexadecimal). With `hexZeroPad`, we fill in 0s to the left until we reach 32 bytes (64 zeros).

```typescript
const arrayLengthSlot = ethers.utils.hexZeroPad('0x2', 32);
// 0x0000000000000000000000000000000000000000000000000000000000000002
const firstElementSlot = ethers.utils.keccak256(arrayLengthSlot);
// 0x405787fa12a823e0f2b7631cc41b3ba8828b3321ca811111fa75cd3aa3bb5ace
```

Now, if we call `getStorageAt` with that slot, we will get the first item stored in the array:

```typescript
let content = await ethers.provider.getStorageAt(contract.address, firstElementSlot);
// 0x000000000000000000000000000000000000000000000000000000000000000a
```

We see that the hexadecimal value of 10, our first element! Now the next elements are stored in a sequentiall order. So if we add 1 to the position of the first element we get the second.

```typescript
// 0x405787fa12a823e0f2b7631cc41b3ba8828b3321ca811111fa75cd3aa3bb5ace
// + 1
// 0x405787fa12a823e0f2b7631cc41b3ba8828b3321ca811111fa75cd3aa3bb5acf
//                                                                  ^
const secondElementSlot = '0x405787fa12a823e0f2b7631cc41b3ba8828b3321ca811111fa75cd3aa3bb5acf';
content = await ethers.provider.getStorageAt(contract.address, secondElementSlot);
// 0x0000000000000000000000000000000000000000000000000000000000000014
```

Which is 20 in hex. And the third element is in the next one:

```typescript
// 0x405787fa12a823e0f2b7631cc41b3ba8828b3321ca811111fa75cd3aa3bb5acf
// +1
// 0x405787fa12a823e0f2b7631cc41b3ba8828b3321ca811111fa75cd3aa3bb5ad0
//                                                                 ^^
```

Finally, we will see an example with mappings.

```solidity
contract StoragePlayground {
  // State variables
  uint256 favNumber; // Storage at slot 0
  bool someBool; // Storage at slot 1
  mapping(uint256 => bool) dictionary; // Storage at slot 2
  address private someAddress; // Storage at slot 3

  constructor() {
    favNumber = 5;
    someBool = true;
    someAddress = 0xaA3052db3062D60643682B1272d00A6BF4A6f5E6;
    dictionary[10] = true;
    dictionary[20] = false;
    dictionary[30] = true;
  }
}
```

In this output, we see that slot 2 is completely empty, unlike the dynamic array, here the length of the mapping is not stored because it is not iterable, and its keys do not have to be consecutive.

```bash
0 -> 0x0000000000000000000000000000000000000000000000000000000000000005
1 -> 0x0000000000000000000000000000000000000000000000000000000000000001
2 -> 0x0000000000000000000000000000000000000000000000000000000000000000
3 -> 0x000000000000000000000000aa3052db3062d60643682b1272d00a6bf4a6f5e6
4 -> 0x0000000000000000000000000000000000000000000000000000000000000000

```

However, to calculate the memory position to store the data, it does something similar to arrays. In this case, the [formula to apply is this](https://docs.soliditylang.org/en/develop/internals/layout_in_storage.html#mappings-and-dynamic-arrays): `keccak256(h(k) . p)`. Where `h` is a function based on the type of the key (could be values, strings and byte arrays), `k` is the dictionary key, `p` is the memory slot of the mapping, and `.` is the concatenation of both.

```typescript
// Convert to hexadecimal the slot 0x2 and the dictionary key
const p = ethers.utils.hexZeroPad('0x2', 32);
const k = ethers.BigNumber.from(10).toHexString();
// For values we only add zeroes
const h_k_ = ethers.utils.hexZeroPad(k, 32);

// Concat
const concat = ethers.utils.concat([h_k_, p]);

// Apply hash
const hashedSlot = ethers.utils.keccak256(concat);

// Get the value at the calculated slot (hashedSlot)
const value = await ethers.provider.getStorageAt(contract.address, hashedSlot);

// This would be the output of hashedSlot and the value for the 3 keys:

// dictionary[10] = true
// Slot  -> 0xd3604db978f6137b0d18816b77b2ce810487a3af08a922e0b184963be5f3adfc
// Value -> 0x0000000000000000000000000000000000000000000000000000000000000001

// dictionary[20] = false
// Slot  -> 0x50d9dffd10eb4437a15e8bb1c50afee98ea231805f136fb9a057e7aaeec448ae
// Value -> 0x0000000000000000000000000000000000000000000000000000000000000000

// dictionary[30] = true
// Slot  -> 0x6ea47ca2f9e3a67b0e336c514aa9f125109f49309b7162caec32e7d27e5c838c
// Value -> 0x0000000000000000000000000000000000000000000000000000000000000001
```

## getStorageAt

As a curiosity about this function, it allows us to access the contents of a memory slot in a contract's storage. If you think about it, you can see everything, as long as you have access to the contract, you can see in which slot something is stored.

As seen in the last example, there are public variables (by default) and private ones (those that have the `private` prefix), so using this function, you can see them all if you have access to the contract code and simply count in which slot the variable is defined. So remember, **never** store sensitive data in the blockchain.

---

## Resources

- [keccak256 playground](https://emn178.github.io/online-tools/keccak_256.html)
- [hex-to-decimal converter](https://www.rapidtables.com/convert/number/hex-to-decimal.html)
- [Solidity documentation](https://docs.soliditylang.org/en/develop/internals/layout_in_storage.html#layout-of-state-variables-in-storage)
- [ethers.utils documentation](https://docs.ethers.io/v4/api-utils.html#)
- [Supporting repository](https://github.com/PatrickAlphaC/hardhat-fund-me-fcc)
- [Adrian Hetman post](https://www.adrianhetman.com/unboxing-evm-storage/)

---

[^1]: Ethereum Virtual Machine. It is an entity supported by the nodes that make up the network. We can see it as a distributed state machine. It does not share resources in terms of computing power with other nodes, but it does share global state. It is capable of executing code.
[^2]: It is a key-value dictionary, it is not iterable and its size is dynamic. Its syntax is `(key-type ⇒ key-value-type) variable-name`. Mappings can be nested.


What types of storage are in Solidity? Memory vs Storage.

All posts