From fb957c8e78219fdec36432d3715facaa9069f1c0 Mon Sep 17 00:00:00 2001 From: 0xKitsune <0xkitsune@protonmail.com> Date: Thu, 31 Oct 2024 13:35:02 -0400 Subject: [PATCH 1/6] update lifecycle of tx --- README.md | 2 - world-chain-builder/docs/pbh_tx_lifecycle.md | 46 ++++++++++++++++++++ 2 files changed, 46 insertions(+), 2 deletions(-) create mode 100644 world-chain-builder/docs/pbh_tx_lifecycle.md diff --git a/README.md b/README.md index 30cddcd..3fa2cf8 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,6 @@ The WorldChain Builder is a custom block builder for the OP Stack that provides ## PBH Transaction Envelope The builder introduces a new EIP-2718 RLP encoded transaction envelope including a [Pbh Payload](https://github.com/worldcoin/world-chain/blob/8d60a1e79dbb3be68db075d49b3d0a8a67e45b3e/world-chain-builder/src/pbh/payload.rs#L50), which contains a World ID proof, proving the transaction was created by a verified human. -```rust - ```rust #[derive(Clone, Debug, PartialEq, Eq)] pub struct WorldChainPooledTransactionsElement { diff --git a/world-chain-builder/docs/pbh_tx_lifecycle.md b/world-chain-builder/docs/pbh_tx_lifecycle.md new file mode 100644 index 0000000..530657f --- /dev/null +++ b/world-chain-builder/docs/pbh_tx_lifecycle.md @@ -0,0 +1,46 @@ +# Lifecycle of a PBH Transaction + +The WorldChain Builder is a custom block builder for the OP Stack that provides Priority Blockspace for Humans (PBH). PBH enables verified World ID users to execute transactions with top of block priority, enabling a more frictionless user experience. This mechanism is designed to ensure that ordinary users aren’t unfairly disadvantaged by automated systems and greatly mitigates the impact of negative impacts of MEV. PBH also enables future flexibility, allowing for a separate EIP-1559-style fee market mechanism for verified transactions. + +The builder introduces a new EIP-2718 RLP encoded transaction envelope 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. + + +## Creating a PBH transaction + +The contents of the PBH transaction envelope simply consists of an [Ethereum typed transaction ](https://eips.ethereum.org/EIPS/eip-2718) and optional semaphore proof, verifying the sender is verified World ID user. In order to create a PBH transaction envelope, first generate an [Ethereum transaction](https://ethereum.org/en/developers/docs/transactions/). + +Next, [create a World ID proof](), **setting the `signal` to the transaction hash of the tx you are verifying**, and set the `externalNullifier` to the following schema `vv-mmyyyy-nn` where: + +- **Version Prefix (vv)**: Indicates the version of the external nullifier schema This should be set to `0`. +- **Date (mmyyyy)**: Indicates the current month and year. +- **PBH Nonce (nn)**: A `u16` value used to rate-limit PBH transactions. + +Upon receiving the PBH transaction envelope, the World Chain Builder first validates the inner Ethereum transaction and then verifies the PBH payload. The builder enforces a transaction limit for each verified user that resets every month, tracked by the PBH nonce specified in the `externalNullifier`. The user creating the PBH envelope must track the nonces used, however nonces can be specified in any order. For example, a user could send a PBH transaction envelope with a PBH nonce of `16`, followed by a PBH nonce of `10` and so on. Transaction validation will be covered further in a later section. + +Below is a quick look at the `PbhTxEnvelope` in its entirety. + +``` +PbhTxEnvelope = { Tx, PbhPayload } +PbhPayload = { externalNullifier, nullifierHash, root, proof } +``` +- `Tx`: Any valid Ethereum typed transaction. +- `externalNullifier`: Unique identifier used to ensure the uniqueness and proper sequencing of PBH transactions formatted as: `vv-mmyyyy-nn`. + +- `nullifierHash`: Hash of the identity nullifier and the external nullifier; used to prevent double-signaling. You can read more [about the nullifier and external nullifier here](https://docs.world.org/world-id/further-reading/protocol-internals#external-nullifier). + +- `root`: Root of the [Merkle tree representing the identity set](https://docs.world.org/world-id/further-reading/protocol-internals#signup-sequencer). This is the root used when creating the inclusion proof necessary to create a semaphore ZK proof. + +- `proof`: The semaphore proof verifying that the sender is a member of the identity set. + + +## Sending the transaction to the Builder + + +## Transaction Validation +// NOTE: PBH transactions are not gossiped or forwarded to the sequencer. All normal transactions are forwarded though + + +## Transaction Priority and Block Production + +// NOTE: mention max gas % + From 9d87fc80d1a09eb00087be7d3b90410c87aa1ddb Mon Sep 17 00:00:00 2001 From: 0xKitsune <0xkitsune@protonmail.com> Date: Thu, 31 Oct 2024 13:45:31 -0400 Subject: [PATCH 2/6] send tx to the builder --- world-chain-builder/docs/pbh_tx_lifecycle.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/world-chain-builder/docs/pbh_tx_lifecycle.md b/world-chain-builder/docs/pbh_tx_lifecycle.md index 530657f..d978e2e 100644 --- a/world-chain-builder/docs/pbh_tx_lifecycle.md +++ b/world-chain-builder/docs/pbh_tx_lifecycle.md @@ -2,12 +2,12 @@ The WorldChain Builder is a custom block builder for the OP Stack that provides Priority Blockspace for Humans (PBH). PBH enables verified World ID users to execute transactions with top of block priority, enabling a more frictionless user experience. This mechanism is designed to ensure that ordinary users aren’t unfairly disadvantaged by automated systems and greatly mitigates the impact of negative impacts of MEV. PBH also enables future flexibility, allowing for a separate EIP-1559-style fee market mechanism for verified transactions. -The builder introduces a new EIP-2718 RLP encoded transaction envelope 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. +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. ## Creating a PBH transaction -The contents of the PBH transaction envelope simply consists of an [Ethereum typed transaction ](https://eips.ethereum.org/EIPS/eip-2718) and optional semaphore proof, verifying the sender is verified World ID user. In order to create a PBH transaction envelope, first generate an [Ethereum transaction](https://ethereum.org/en/developers/docs/transactions/). +The contents of the PBH transaction envelope simply consists of an [Ethereum typed transaction ](https://eips.ethereum.org/EIPS/eip-2718) and optional semaphore proof, ensuring that the sender is verified World ID user. In order to create a PBH transaction envelope, first generate an [Ethereum transaction](https://ethereum.org/en/developers/docs/transactions/). Next, [create a World ID proof](), **setting the `signal` to the transaction hash of the tx you are verifying**, and set the `externalNullifier` to the following schema `vv-mmyyyy-nn` where: @@ -15,7 +15,7 @@ Next, [create a World ID proof](), **setting the `signal` to the transaction has - **Date (mmyyyy)**: Indicates the current month and year. - **PBH Nonce (nn)**: A `u16` value used to rate-limit PBH transactions. -Upon receiving the PBH transaction envelope, the World Chain Builder first validates the inner Ethereum transaction and then verifies the PBH payload. The builder enforces a transaction limit for each verified user that resets every month, tracked by the PBH nonce specified in the `externalNullifier`. The user creating the PBH envelope must track the nonces used, however nonces can be specified in any order. For example, a user could send a PBH transaction envelope with a PBH nonce of `16`, followed by a PBH nonce of `10` and so on. Transaction validation will be covered further in a later section. +Upon receiving the PBH transaction envelope, the World Chain Builder first validates the inner Ethereum transaction and then verifies the PBH payload. The builder enforces a transaction limit for each verified user that resets every month (eg. 50 txs per month), tracked by the PBH nonce specified in the `externalNullifier`. The user creating the PBH envelope must track which nonces they have used, however nonces can be specified in any order. For example, a user could send a PBH tx envelope with a PBH nonce of `16`, followed by a PBH nonce of `10` and so on. Additional transaction validation will be covered further in a later section. Below is a quick look at the `PbhTxEnvelope` in its entirety. @@ -24,7 +24,7 @@ PbhTxEnvelope = { Tx, PbhPayload } PbhPayload = { externalNullifier, nullifierHash, root, proof } ``` - `Tx`: Any valid Ethereum typed transaction. -- `externalNullifier`: Unique identifier used to ensure the uniqueness and proper sequencing of PBH transactions formatted as: `vv-mmyyyy-nn`. +- `externalNullifier`: String identifier used to ensure the uniqueness and proper sequencing of PBH transactions formatted as: `vv-mmyyyy-nn`. - `nullifierHash`: Hash of the identity nullifier and the external nullifier; used to prevent double-signaling. You can read more [about the nullifier and external nullifier here](https://docs.world.org/world-id/further-reading/protocol-internals#external-nullifier). @@ -35,6 +35,16 @@ PbhPayload = { externalNullifier, nullifierHash, root, proof } ## Sending the transaction 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. + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -d "{\"jsonrpc\":\"2.0\",\"method\":\"eth_sendRawTransaction\",\"params\":[\"$PBH_TX_BYTES\"],\"id\":480}" \ + $BUILDER_ENDPOINT +``` + + ## Transaction Validation // NOTE: PBH transactions are not gossiped or forwarded to the sequencer. All normal transactions are forwarded though From 3a0e9cdc1b6f8727217d2332b557666d78af467c Mon Sep 17 00:00:00 2001 From: 0xKitsune <0xkitsune@protonmail.com> Date: Thu, 31 Oct 2024 13:52:49 -0400 Subject: [PATCH 3/6] add readme links --- README.md | 76 ++----------------------------------------------------- 1 file changed, 2 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 3fa2cf8..a8ddefe 100644 --- a/README.md +++ b/README.md @@ -2,82 +2,10 @@ The WorldChain Builder is a custom block builder for the OP Stack that provides Priority Blockspace for Humans (PBH). PBH enables verified World ID users to execute transactions with top of block priority, enabling a more frictionless user experience. This mechanism is designed to ensure that ordinary users aren’t unfairly disadvantaged by automated systems and greatly mitigates the impact of negative impacts of MEV. PBH also enables future flexibility, allowing for a separate EIP-1559-style fee market mechanism for verified transactions. - -## PBH Transaction Envelope -The builder introduces a new EIP-2718 RLP encoded transaction envelope including a [Pbh Payload](https://github.com/worldcoin/world-chain/blob/8d60a1e79dbb3be68db075d49b3d0a8a67e45b3e/world-chain-builder/src/pbh/payload.rs#L50), which contains a World ID proof, proving the transaction was created by a verified human. - -```rust -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct WorldChainPooledTransactionsElement { - pub inner: PooledTransactionsElement, - pub pbh_payload: Option, -} - -/// The payload of a PBH transaction -/// -/// Contains the semaphore proof and relevent metadata -/// required to to verify the pbh transaction. -#[derive(Clone, Debug, RlpEncodable, RlpDecodable, PartialEq, Eq, Default)] -pub struct PbhPayload { - /// A string containing a prefix, the date marker, and the pbh nonce - pub external_nullifier: String, - /// A nullifier hash used to keep track of - /// previously used pbh transactions - pub nullifier_hash: Field, - /// The root of the merkle tree for which this proof - /// was generated - pub root: Field, - /// The actual semaphore proof verifying that the sender - /// is included in the set of orb verified users - pub proof: Proof, -} - -``` - -## PBH Payload - -### External Nullifier - -The **External Nullifier** is a structured identifier used to ensure the uniqueness and proper sequencing of PBH transactions. Its format is defined as: - -### Schema -`vv-mmyyyy-nn` - -- **Version Prefix (vv)**: Represents the version of the nullifier. - - Validation: Must match the current version. - -- **Date (mmyyyy)**: Represents the month and year. - - Validation: Must match the current month and year. - -- **PBH Nonce (nn)**: A `u16` value used to rate-limit PBH transactions. - - Validation: - - The PBH Nonce must be ≤ 30 by default. - - This nonce limits the number of PBH transactions each user can submit per month. - - It resets at the beginning of each month and increments monotonically from 0 to `num_pbh_txs`. - - Any nonce greater than `num_pbh_txs` will be invalidated and excluded from the transaction pool. - -### Nullifier Hash - -The **Nullifier Hash** ensures that each PBH transaction is unique at the time of validation. - -- **Validation**: - - The nullifier hash must be unique during transaction validation to prevent duplicate transactions. - - -### Root - -The **Root** represents the root of the Merkle tree for which the proof was generated. - -- **Validation**: - - Must match the `latestRoot` stored in the `OpWorldId` contract on L2. - -- **Additional Considerations**: - - If the root has not yet synchronized with L1, there may be a window where a valid proof is perceived as invalid. - - To avoid transaction validation errors, the root should be read from L2 and asserted to match the root on L1 before submitting the transaction. - - +To learn more about how PBH works, check out the docs detailing [the PBH Transaction Lifecycle](world-chain-builder/docs/pbh_tx_lifecycle.md) as well as [World's blog post covering World Chain's builder architecture](https://world.org/blog/engineering/introducing-pbh-priority-blockspace-for-humans). + ## Running the Devnet To spin up a OP Stack devnet with `rollup-boost` and the `world-chain-builder` deployed, make sure that you have [just](https://github.com/casey/just?tab=readme-ov-file) installed, and docker daemon running. Then simply run the following command. From b6e196ea22d31abee16789fc52aa16f5391bda5a Mon Sep 17 00:00:00 2001 From: 0xKitsune <0xkitsune@protonmail.com> Date: Thu, 31 Oct 2024 13:55:45 -0400 Subject: [PATCH 4/6] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a8ddefe..8a671d0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # World Chain Builder -The WorldChain Builder is a custom block builder for the OP Stack that provides Priority Blockspace for Humans (PBH). PBH enables verified World ID users to execute transactions with top of block priority, enabling a more frictionless user experience. This mechanism is designed to ensure that ordinary users aren’t unfairly disadvantaged by automated systems and greatly mitigates the impact of negative impacts of MEV. PBH also enables future flexibility, allowing for a separate EIP-1559-style fee market mechanism for verified transactions. +The World Vhain Builder is a custom block builder for the OP Stack that provides Priority Blockspace for Humans (PBH). PBH enables verified World ID users to execute transactions with top of block priority, enabling a more frictionless user experience. This mechanism is designed to ensure that ordinary users aren’t unfairly disadvantaged by automated systems and greatly mitigates the impact of negative impacts of MEV. PBH also enables future flexibility, allowing for a separate EIP-1559-style fee market mechanism for verified transactions. To learn more about how PBH works, check out the docs detailing [the PBH Transaction Lifecycle](world-chain-builder/docs/pbh_tx_lifecycle.md) as well as [World's blog post covering World Chain's builder architecture](https://world.org/blog/engineering/introducing-pbh-priority-blockspace-for-humans). From 134e6c0ba17f883407241db4077e6806cd7ee128 Mon Sep 17 00:00:00 2001 From: 0xKitsune <0xkitsune@protonmail.com> Date: Thu, 31 Oct 2024 13:56:45 -0400 Subject: [PATCH 5/6] fmt --- world-chain-builder/docs/pbh_tx_lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/world-chain-builder/docs/pbh_tx_lifecycle.md b/world-chain-builder/docs/pbh_tx_lifecycle.md index d978e2e..6a8dc11 100644 --- a/world-chain-builder/docs/pbh_tx_lifecycle.md +++ b/world-chain-builder/docs/pbh_tx_lifecycle.md @@ -7,7 +7,7 @@ The builder introduces a new [EIP-2718 RLP encoded transaction envelope](https:/ ## Creating a PBH transaction -The contents of the PBH transaction envelope simply consists of an [Ethereum typed transaction ](https://eips.ethereum.org/EIPS/eip-2718) and optional semaphore proof, ensuring that the sender is verified World ID user. In order to create a PBH transaction envelope, first generate an [Ethereum transaction](https://ethereum.org/en/developers/docs/transactions/). +The contents of the PBH tx envelope simply consists of an [Ethereum typed transaction ](https://eips.ethereum.org/EIPS/eip-2718) and optional semaphore proof ensuring that the sender is verified World ID user. In order to create a PBH transaction envelope, first generate an [Ethereum transaction](https://ethereum.org/en/developers/docs/transactions/). Next, [create a World ID proof](), **setting the `signal` to the transaction hash of the tx you are verifying**, and set the `externalNullifier` to the following schema `vv-mmyyyy-nn` where: From 69828be51f410bb53a37e2ecc4ac355f217f82e5 Mon Sep 17 00:00:00 2001 From: 0xKitsune <0xkitsune@protonmail.com> Date: Thu, 31 Oct 2024 13:59:08 -0400 Subject: [PATCH 6/6] spacing --- world-chain-builder/docs/pbh_tx_lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/world-chain-builder/docs/pbh_tx_lifecycle.md b/world-chain-builder/docs/pbh_tx_lifecycle.md index 6a8dc11..b9975ec 100644 --- a/world-chain-builder/docs/pbh_tx_lifecycle.md +++ b/world-chain-builder/docs/pbh_tx_lifecycle.md @@ -1,6 +1,6 @@ # Lifecycle of a PBH Transaction -The WorldChain Builder is a custom block builder for the OP Stack that provides Priority Blockspace for Humans (PBH). PBH enables verified World ID users to execute transactions with top of block priority, enabling a more frictionless user experience. This mechanism is designed to ensure that ordinary users aren’t unfairly disadvantaged by automated systems and greatly mitigates the impact of negative impacts of MEV. PBH also enables future flexibility, allowing for a separate EIP-1559-style fee market mechanism for verified transactions. +The World Chain Builder is a custom block builder for the OP Stack that provides Priority Blockspace for Humans (PBH). PBH enables verified World ID users to execute transactions with top of block priority, enabling a more frictionless user experience. This mechanism is designed to ensure that ordinary users aren’t unfairly disadvantaged by automated systems and greatly mitigates the impact of negative impacts of MEV. PBH also enables future flexibility, allowing for a separate EIP-1559-style fee market mechanism for verified transactions. 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.