Merge pull request #49 from worldcoin/kit/readme

Update Readme

README.md

@@ -1,22 +1,95 @@
-# world-chain-builder
+# World Chain Builder
 
-## Priority Blockspace for Humans (PBH)
+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.
 
-### Intro
 
-The general idea behind PBH transaction is to allow orb verified users to submit a limited number of priority transactions.
-Priority transactions are alloted a fixed amount of the total available block space, and are executed at the top of the block before other non verified transactions.
-This is useful as it provides verified users a way to submit transactions without competing with bots on fees or being exposed to potentially harmful MEV activity.
+## 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.
 
-### Implementation
+```rust
 
-Pbh transactions are composed of any regular rlp encoded optimism transaction followed by an rlp encoded PBH payload.
-The PBH payload contains the following fields:
+```rust
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct WorldChainPooledTransactionsElement {
+    pub inner: PooledTransactionsElement,
+    pub pbh_payload: Option<PbhPayload>,
+}
 
-`external_nullifier` - A string containing a prefix, the date marker, and the pbh nonce
+/// 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,
+}
 
-`nullifier_hash` - A nullifier hash used to keep track of previously used pbh transactions
+```
 
-`root` - The root of the merkle tree for which this proof was generated
+## PBH Payload
 
-`proof` - The actual semaphore proof verifying that the sender is included in the set of orb verified users
+### 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.
+
+
+
+
+
+## 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.
+
+```
+just devnet-up
+```
+
+To stop the devnet and clean up all resources, run the command below.
+
+```
+just devnet-down
+```