Skip to content

Commit

Permalink
fix fmt
Browse files Browse the repository at this point in the history
  • Loading branch information
0xKitsune committed Oct 31, 2024
1 parent 116da16 commit 99fc112
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 1 deletion.
4 changes: 4 additions & 0 deletions world-chain-builder/docs/pbh_architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

World Chain is an OP Stack chain, enabling priority blockspace for humans through the World Chain Builder. In order to fully understand the builder, lets quickly review how transaction inclusion works within the OP Stack. The diagram below demonstrates an abridged version of the lifecycle of a transaction on Optimistic Rollups.

</br>

## Block Production on the OP Stack
![OP Stack Architecture](../../assets/op-stack.png)
Expand All @@ -12,6 +13,9 @@ The [Engine API](https://specs.optimism.io/protocol/exec-engine.html#engine-api)

Transaction ordering occurs in the payload builder which is responsible for building a new block in response to a fork choice update (FCU) message from the `op-node`. Note that transaction ordering within the payload builder is not enforced at the protocol level. A block builder can construct a valid block with any combination of pending transactions, in any order. Eventually though, it may be possible to enforce ordering at a protocol level through the derivation pipeline. Currently, there is an experimental spec [outlining a transaction ordering policy](https://github.com/ethereum-optimism/specs/blob/feat/tx-ordering-policy/specs/experimental/tx-ordering-policy.md#transaction-ordering-policy-1) for OP Stack chains.


</br>

## Block Production on World Chain
To enable PBH for verified users on World Chain, an external block builder has been developed that prioritizes transactions with a valid World ID proof (For more information on what PBH transactions are, check out the [Lifecycle of a PBH Transaction docs](./pbh_tx_lifecycle.md)). World Chain uses [rollup-boost](https://github.com/flashbots/rollup-boost), a OP stack "sidecar" service that orchestrates block production between external block builders and the OP stack sequencer.

Expand Down
10 changes: 9 additions & 1 deletion world-chain-builder/docs/pbh_tx_lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ The World Chain Builder is a custom block builder for the OP Stack that provides

The builder introduces a new [EIP-2718 RLP encoded transaction envelope](https://eips.ethereum.org/EIPS/eip-2718) including the necessary data to verify the transaction was created by a valid World ID user. To get a deeper understanding of PBH, lets walk through the life cycle of a transaction.

</br>

## Creating a PBH transaction

Expand Down Expand Up @@ -32,8 +33,10 @@ PbhPayload = { externalNullifier, nullifierHash, root, proof }

- `proof`: The semaphore proof verifying that the sender is a member of the identity set.

</br>

## Sending the transaction to the Builder

## Sending transactions to the Builder

Since the PBH tx envelope is a valid [EIP-2718 Typed Transaction Envelope](https://eips.ethereum.org/EIPS/eip-2718), it can be sent to the builder via the `eth_sendRawTransaction` endpoint, just like any other node that implements the Engine API.

Expand All @@ -46,6 +49,9 @@ curl -X POST \

Note that the builder is built on top of `op-reth` meaning that any valid transaction that can be sent to Optimism can also be sent to the builder. All transactions without a PBH payload attached are also forwarded to the sequencer.


</br>

## Transaction Validation

Once the World Chain Builder receives a new PBH tx envelope, it first verifies that the transaction attached is valid. Next, the PBH payload is verified, ensuring that the `externalNullifier` schema matches the expected version and that the PBH nonce does not exceed the maximum amount of transactions per period.
Expand All @@ -54,6 +60,8 @@ Following this, the nullifier hash is checked to ensure that this user has not c

After successful validation, the transaction is inserted into the mempool.

</br>

## Transaction Priority and Block Production

When the sequencer sends a new `ForkChoiceUpdate` notifying that a new block should be produced, the builder will fetch the best transactions from the transaction pool to fill the block. The World Chain Builder tx pool implements a custom ordering policy which gives priority to transactions with a valid PBH payload. When the builder is including a PBH tx in the block, the inner transaction is unwrapped and the PBH payload is dropped. There is no additional data included in the sealed block and all World Chain blocks follow the same specification any other superchain compliant OP Stack chain.
Expand Down

0 comments on commit 99fc112

Please sign in to comment.