Skip to content

Commit

Permalink
Add info about event_inbox_root on the header (#571)
Browse files Browse the repository at this point in the history
  • Loading branch information
@MitchTurner
MitchTurner authored Apr 23, 2024
1 parent 0dbcea0 commit e09a271
Show file tree
Hide file tree
Showing 5 changed files with 77 additions and 9 deletions.
1 change: 1 addition & 0 deletions src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
- [Cryptographic Primitives](./protocol/cryptographic-primitives.md)
- [Storage Slot Initialization](./protocol/storage-initialization.md)
- [Block Header Format](./protocol/block-header.md)
- [Layer 1 Relayer/Bridge Protocol](./protocol/relayer.md)
- [Application Binary Interface (ABI)](./abi/index.md)
- [JSON ABI Format](./abi/json-abi-format.md)
- [Receipts](./abi/receipts.md)
Expand Down
1 change: 1 addition & 0 deletions src/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ This book specifies the Fuel protocol, including the Fuel Virtual Machine
- [**Application Binary Interface (ABI)**](./abi/index.md) - Low-level details on interfacing with Fuel bytecode.
- [**Storage Slot Initialization**](./protocol/storage-initialization.md) - JSON format for contract storage slot initialization.
- [**Block Header Format**](./protocol/block-header.md) - The Fuel block header format.
- [**Relayer/Bridge**](./protocol/relayer.md) - The Fuel relayer/bridge protocol.

## FuelVM

Expand Down
19 changes: 10 additions & 9 deletions src/protocol/block-header.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@

The application header is a network-agnostic block header. Different [networks](../networks/index.md) may wrap the application header in a consensus header, depending on their consensus protocol.

| name | type | description |
|----------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `da_height` | `uint64` | Height of the data availability layer up to which (inclusive) input messages are processed. |
| `consensusParametersVersion` | `uint32` | The version of the consensus parameters used to execute this block. |
| `stateTransitionBytecodeVersion` | `uint32` | The version of the state transition bytecode used to execute this block. |
| `txCount` | `uint64` | Number of [transaction](../tx-format/transaction.md)s in this block. |
| `message_receipt_count` | `uint64` | Number of [output message](../abi/receipts.md#messageout-receipt)s in this block. |
| `txRoot` | `byte[32]` | [Merkle root](./cryptographic-primitives.md#binary-merkle-tree) of [transaction](../tx-format/transaction.md)s in this block. |
| `message_receipt_root` | `byte[32]` | [Merkle root](./cryptographic-primitives.md#binary-merkle-tree) of [output message](../abi/receipts.md#messageout-receipt)s [`messageId`](../identifiers/utxo-id.md#message-id) in this block. |
| name | type | description |
|----------------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `da_height` | `uint64` | Height of the data availability layer up to which (inclusive) input messages are processed. |
| `consensusParametersVersion` | `uint32` | The version of the consensus parameters used to execute this block. |
| `stateTransitionBytecodeVersion` | `uint32` | The version of the state transition bytecode used to execute this block. |
| `txCount` | `uint64` | Number of [transaction](../tx-format/transaction.md)s in this block. |
| `message_receipt_count` | `uint64` | Number of [output message](../abi/receipts.md#messageout-receipt)s in this block. |
| `txRoot` | `byte[32]` | [Merkle root](./cryptographic-primitives.md#binary-merkle-tree) of [transaction](../tx-format/transaction.md)s in this block. |
| `message_outbox_root` | `byte[32]` | [Merkle root](./cryptographic-primitives.md#binary-merkle-tree) of [output message](../abi/receipts.md#messageout-receipt)s [`messageId`](../identifiers/utxo-id.md#message-id) in this block. |
| `event_inbox_root` | `byte[32]` | [Merkle root](./cryptographic-primitives.md#binary-merkle-tree) of all [events](./relayer.md) imported from L1 in this block. The order of the events added to the Merkle tree is the L1 block order, and the index of each event within each block |
1 change: 1 addition & 0 deletions src/protocol/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@
- [Cryptographic Primitives](./cryptographic-primitives.md)
- [Storage Slot Initialization](./storage-initialization.md)
- [Block Header Format](./block-header.md)
- [Relayer/Bridge](./relayer.md)
64 changes: 64 additions & 0 deletions src/protocol/relayer.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Layer 1 Relayer/Bridge Protocol

The Fuel relayer/bridge protocol is a set of rules that govern the interaction between the Fuel blockchain and the
Layer 1 (L1) blockchain (e.g. Ethereum).

The Fuel blockchain can emit messages that will be processed by the smart contract on the L1 blockchain. The smart
contract on the L1 can also emit events that will be processed by the Fuel blockchain.
This is used to move any data between the L1 blockchain and the Fuel blockchain.

## Fuel Message Outbox

The message outbox is the set of messages sent to the L1 blockchain from the Fuel blockchain.

## Fuel Event Inbox

The event inbox is the set of events received from the L1 blockchain by the Fuel blockchain.

The block producer will receive the list of events from the L1 by some relayer, and then include both the count and the
merkle root of the events in the block header.

There are two types of events that can be received from the L1:

1. Messages
2. Transactions

### Messages

An arbitrary message sent from the L1 to the Fuel blockchain. This can be used to move assets from the L1
to the Fuel blockchain or send other arbitrary information to the Fuel blockchain.

| name | type | description |
|-------------|---------|---------------------------------------------------------------------|
| `sender` | `bytes[32]` | The identity of the sender of the message on the L1 |
| `recipient` | `bytes[32]` | The recipient of the message on the Fuel Blockchain |
| `nonce` | `bytes[32]` | Unique identifier of the message assigned by the L1 contract |
| `amount` | `uint64` | The amount of the base asset transfer |
| `data` | `byte[]` | Arbitrary message data |

### Transactions

These are transactions that are submitted on the L1 that must be executed on the Fuel blockchain.
This "Forced Transaction Inclusion" is a security feature that allows participants of the Fuel Blockchain to access
their funds in the (unlikely) event that the Fuel blockchain block production is compromised or malicious, e.g. the
block producer is censoring transactions.

| name | type | description |
|--------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `nonce` | `bytes[32]` | Unique identifier of the transaction assigned by the L1 contract |
| `max_gas` | `uint64` | The maximum amount of gas allowed to use on Fuel Blockchain |
| `serialized_transaction` | `byte[]` | The serialized transaction bytes following canonical serialization |

The `serialized_transaction` can be any [transaction variant](../tx-format/transaction.md) except the `Mint` transaction, which
is only ever created by the block producer. `Mint` transactions will be rejected by the Fuel blockchain if they are relayed
from the L1.

### Ordering

It is important that the L1 events are ordered correctly when they are relayed to the Fuel blockchain. The events will
be ordered by the L1 block height and then by the index of the event within the block.

The order is important because a merkle root will be generated each time events from L1 are included in a Fuel block.
This merkle root can later be used to prove that an arbitrary event was included on that block without having to store
every event on the block header explicitly. Just the merkle root will be on the [block header](./block-header.md).
The order of the events affects the value of the merkle root.

0 comments on commit e09a271

Please sign in to comment.