diff --git a/docs/move-funds.md b/docs/acquire-testnet-tokens.md similarity index 77% rename from docs/move-funds.md rename to docs/acquire-testnet-tokens.md index 18c9df1..89c74dc 100644 --- a/docs/move-funds.md +++ b/docs/acquire-testnet-tokens.md @@ -1,11 +1,11 @@ --- -title: Move Funds to UniFi -slug: /move-funds +title: Acquire Testnet Tokens +slug: /acquire-testnet-tokens --- -# Moving Funds to UniFi +# Acquire Testnet Tokens -This guide will help you move your funds from the L1 Testnet to UniFi Rollup. Follow the steps below to get started. +This guide will help you acquire UniFi Testnet tokens. Follow the steps below to get started. ## 1. Install a Compatible Wallet @@ -17,7 +17,7 @@ To interact with UniFi Rollup, you need an Ethereum wallet like MetaMask or any ## 2. Add the L2 Testnet to MetaMask -To connect to the UniFi Helder Testnet, follow these steps: +To connect to the UniFi Testnet, follow these steps: 1. Open MetaMask and click on the network dropdown. 2. Select **Add network** → **Add a network manually**. diff --git a/docs/bridge-ui.md b/docs/bridge-ui.md index 0939cc1..4ef7e38 100644 --- a/docs/bridge-ui.md +++ b/docs/bridge-ui.md @@ -3,6 +3,10 @@ title: How to use UniFi Bridge slug: /bridge-ui --- +:::info + Bridging is currently paused as testnet access is being rolled out gradually. Bridging will be enabled in the next few weeks. +::: + # Using the UniFi Bridge In order to use the UniFi Rollup Bridge, you need to have a compatible wallet and some funds on the L1 network. diff --git a/docs/developers/concepts/tee-multi-prover.md b/docs/developers/concepts/tee-multi-prover.md new file mode 100644 index 0000000..86758ab --- /dev/null +++ b/docs/developers/concepts/tee-multi-prover.md @@ -0,0 +1,50 @@ +--- +title: TEE Multi Prover +slug: /developers/concepts/tee-multi-prover +--- + +## Background + +The defining characteristic of a rollup is the ability to push L2 state updates to L1. Typically, either fraud proofs or validity proofs are used to ensure the correctness of each state update. + +Fraud and validity proofs rely on the strong assumption that the underlying construction and implementation of the proof system are correct. Unfortunately, proof systems are complex pieces of code prone to bugs and errors, and it is impossible to guarantee they are infallible. For this reason, a diverse set of proof systems is essential to safeguard the overall robustness of the system - an idea that has reverberated in multiple places. Different proof systems act as a counter-check against each other: by comparing their outputs against each other we can identify potential discrepancies - similar to differential testing. + +We propose implementing an additional prover system by leveraging Trusted Execution Environment (TEE) technology because this approach yields performance without the complexities associated with e.g., ZK circuits. + +## Brief Overview + +![Brief Overview](/img/tee-multi-prover/overview.png) +*(Note: This design represents the ideal approach and may differ from the existing implementation.)* + +This diagram illustrates how the TEE Validity Proof interacts with the L1 rollup contract: + 1. Whenever the prover relayer needs to update the rollup state on L1, it sends a Proof of Block to the TEE Prover. The Proof of Block contains all the necessary states, enabling the TEE Prover to perform stateless state transitions. + 2. The TEE Prover executes the blocks based on the Proof of Block and generates a TEE Validity Proof, which is then returned to the prover relayer. + 3. The prover relayer submits the updated state along with the proofs to the L1 Rollup Contract. + +## The Case for Using TEEs + +1. TEEs Have Good Performance: TEEs provide reliable, fast, and cost-effective computation. The computational overhead of TEEs is minimal (and can even be negligible, depending on the specific TEE technology). This allows TEEs to perform state transitions with very low latency and high efficiency. For example, based on our tests, Intel TDX introduces less than 1% performance overhead, and the time required to generate a proof is approximately the same as the time needed to execute a block. +2. TEEs can be Used Despite Not Being Infallible: A major concern surrounding TEEs, especially Intel SGX, is that they are frequently compromised. While it is true that vulnerabilities related to TEEs continue to be discovered, it is worth highlighting that these vulnerabilities are not fatal and can't be exploited indefinitely once they are patched - existing exploits are implementation bugs that do not undermine the architectural design of TEEs. Moreover, these vulnerabilities are often difficult, or even impossible, to exploit unless certain conditions are met, e.g., Aepic Leak allows an attacker to access SGX's most precious secrets, but cannot be exploited unless APIC registers are exposed. TEEs are also improving, and more technologies are emerging such as AMD SEV, Intel TDX, and AWS Nitro Enclaves. Lastly, if the vulnerability of one TEE is particularly concerning, a committee consisting of different TEE technologies (e.g., Intel + AMD + AWS) can be employed to increase the security of the overall system - in this scenario, a potential attacker would need to exploit multiple TEE technologies at the same time, making it increasingly difficult to mount an attack. + +## On-Chain Proof Verification + +During the on-chain proof verification process, the following checks are performed: + 1. The software of TEE Prover is verified to ensure it aligns with the expected version and has not been tampered with. + 2. The TEE firmware and SDK of the virtual machine hosting the TEE Prover are confirmed to be up-to-date. + 3. The initial state of the proof for the state transition matches the current state on-chain. + +The attestation report provides the necessary information for points 1 and 2, and we use the [automata-dcap-attestation](https://github.com/automata-network/automata-dcap-attestation) to verify its validity. + +A attestation report verification costs approximately 3M gas. To reduce this expense, we use a ProverRegistry to separate the attestation and rollup processes, allowing a single attestation to support multiple state rollups during its validity period. + +The process is as follows: + 1. A secp256k1 key is randomly generated inside the TEE. + 2. When generating the attestation report, the key is embedded into the attestation report's user data. + 3. Upon submission of the attestation report to the ProverRegistry, the public key is recorded. + 4. When the TEE Prover provides a proof for a state transition, it signs the result using the ephemeral key. + 5. During proof verification, the ProverRegistry uses ecrecover to retrieve the public key and validate it against the recorded key. + +With this optimization, the verification cost for a single proof is reduced to no more than 10k gas. + + +![workflow](/img/tee-multi-prover/workflow.png) \ No newline at end of file diff --git a/docs/developers/reference/opcodes.md b/docs/developers/reference/opcodes.md index 58e5cba..f25bd8b 100644 --- a/docs/developers/reference/opcodes.md +++ b/docs/developers/reference/opcodes.md @@ -23,7 +23,7 @@ The following opcodes are not supported in UniFi: | Opcode | Name | Solidity Equivalent | Rollup Behaviour | Ethereum L1 Behaviour | |--------|-----------|---------------------|----------------------------------------------|--------------------------------------| -| 41 | COINBASE | block.coinbase | Returns the address of the L2 block proposer | Gets the block’s beneficiary address | +| 41 | COINBASE | block.coinbase | Returns the address of the L2 block proposer | Gets the block's beneficiary address | | 42 | TIMESTAMP | block.timestamp | Timestamp of the L2 block | Timestamp of the L1 block | | 43 | NUMBER | block.number | L2 block number | Gets the L1 block number | | 48 | BASEFEE | block.basefee | Returns the L2 base fee | Returns the base fee | diff --git a/docs/developers/reference/rpc-endpoints.md b/docs/developers/reference/rpc-endpoints.md index 774d07b..ead5b7c 100644 --- a/docs/developers/reference/rpc-endpoints.md +++ b/docs/developers/reference/rpc-endpoints.md @@ -5,11 +5,11 @@ slug: /developers/rollup/reference/rpc-endpoints ## UniFi Testnet -| Parameter | Value | -|--------------------|-------------------------------------| -| Network Name | `UniFi Testnet` | -| Chain ID | `8787` | -| Currency Symbol | ETH | -| Block Explorer | TODO: | -| Sequencer URL | TODO: | -| Contract Addresses | See [here](./contract-addresses.md) | +| Parameter | Value | +|--------------------|------------------------------------------| +| Network Name | `UniFi Testnet` | +| Chain ID | `8787` | +| Currency Symbol | ETH | +| Block Explorer | https://testnet-explorer-unifi.puffer.fi | +| Sequencer URL | https://testnet-rpc-unifi.puffer.fi | +| Contract Addresses | See [here](./contract-addresses.md) | diff --git a/docs/developers/rollup/smart-contracts/deploy-foundry.md b/docs/developers/rollup/smart-contracts/deploy-foundry.md index a1dc6e9..bf8f775 100644 --- a/docs/developers/rollup/smart-contracts/deploy-foundry.md +++ b/docs/developers/rollup/smart-contracts/deploy-foundry.md @@ -7,7 +7,7 @@ slug: /developers/rollup/smart-contracts/foundry Before you begin, ensure you've: -1. [Set up your wallet and have bridged UniFi tokens successfully](../../../move-funds.md). +1. [Set up your wallet and have acquired Testnet tokens](../../../acquire-testnet-tokens.md). 2. Downloaded and installed Foundry: ```bash diff --git a/docs/developers/rollup/smart-contracts/deploy-hardhat.md b/docs/developers/rollup/smart-contracts/deploy-hardhat.md index 711f73f..1140791 100644 --- a/docs/developers/rollup/smart-contracts/deploy-hardhat.md +++ b/docs/developers/rollup/smart-contracts/deploy-hardhat.md @@ -7,7 +7,7 @@ slug: /developers/rollup/smart-contracts/hardhat Before you begin, ensure you: -1. [Set up your wallet and have bridged UniFi tokens successfully](../../../move-funds.md). +1. [Set up your wallet and acquired Tesntet tokens](../../../acquire-testnet-tokens.md). 2. [Set up your Hardhat environment](https://hardhat.org/tutorial/setting-up-the-environment#2.-setting-up-the-environment). ## Create a Hardhat project diff --git a/docs/intro.md b/docs/intro.md index 788809d..fe9be04 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,11 +1,11 @@ --- -title: About UniFi +title: Hello UniFi 🐡 slug: / --- # About UniFi Rollup -Puffer's UniFi is an Ethereum Layer 2 (L2) rollup solution designed to address the fragmentation of Ethereum, +Puffer's UniFi is an Ethereum Layer 2 (L2) based rollup solution designed to address the fragmentation of Ethereum, enhance value within the L1 network, and provide credibly neutral transaction sequencing, all while maintaining an intuitive user experience that supports mass adoption. @@ -30,6 +30,6 @@ making it an ideal solution for those seeking scalability without sacrificing de ### Get Started with UniFi Rollup -To begin using UniFi, start by moving your testnet tokens using the [Move Funds to UniFi guide](/move-funds). +To begin using UniFi, start by [acquiring Testnet tokens](/acquire-testnet-tokens). By leveraging UniFi's Ethereum-based rollup, users can enjoy an efficient, decentralized, and unified experience while contributing to the long-term health of the Ethereum ecosystem. diff --git a/docs/protocol/overview.md b/docs/protocol/overview.md new file mode 100644 index 0000000..8f7e1e5 --- /dev/null +++ b/docs/protocol/overview.md @@ -0,0 +1,46 @@ +--- +title: Overview +slug: /protocol/overview +--- + +:::info +UniFi is an Ethereum Based Rollup with enabled preconfirmations. +::: + +## UniFi Walkthrough +![Based sequencing](/img/rollup/based-sequencing.png) + +### 1️⃣ Transaction Submission +The flow begins with users submitting **rollup transactions** to **UniFi Sequencers**. Sequencers are responsible for transaction aggregation and ordering for the rollup. They play a critical role in offering **preconfirmations** to users when possible. + +**Preconfirmations** are essentially "soft promises" from the sequencers that the transactions will be included in the next L1 block. These preconfirmations come with economic guarantees backed by penalties (slashing conditions) to ensure sequencer reliability. If a sequencer fails to include a transaction it has preconfirmed, it risks being slashed. + +### 2️⃣ Block Proposal +Once the sequencer has aggregated enough transactions, it bundles them into a **block**. This block is then **proposed** to UniFi's **Rollup Contract** on the Ethereum L1. At this stage, no execution is performed. Ethereum validators simply record the block's ordered transactions on the L1, and only transaction validation is performed on a contract level. It's important to note that Ethereum validators are responsible for the order of inclusion of these **proposed block** transactions in the L1 chain, which is where the "based"-ness of UniFi comes into play. + +### 3️⃣ Block Insertion +When a proposed block is successfully included in the Ethereum L1 chain, the **UniFi Client** listens for this event. The client: + 1. Extracts the ordered transaction data from the rollup contract. + 2. Constructs an **L2 block** using this transaction data. + 3. Sends the L2 block to the **L2 Execution Client** (a modified Geth client). + +Once the block is executed by the L2 Execution Client, the **L2 state** is updated, and the block is officially added to the L2 chain. + +### 4️⃣ Block Proving +The last step is to prove to the L1 that the block has been executed correctly on the L2. This is where **UniFi Provers** come into play. They listen for newly inserted L2 blocks (without a proof) and generate cryptographic proofs to validate their correctness. + +To generate a proof, provers create a **Proof of Block (PoB)** statement themselves, which they send over to an **Intel TDX TEE** for attestation. The TEE acts as a trusted computation enclave that uses the PoB to securely re-execute the block's transactions and verify the state transitions. Once the re-execution completes: + +- The TEE generates an **attestation** that ensures the L2 block's integrity. +- The attestation and cryptographic proof are submitted to UniFi's L1 contract on Ethereum. +- The L1 contract verifies the proof, ensuring that the state transitions are valid and match the ordered transactions. +- Once verified, the block is considered **proven**, and the L1 state is updated to reflect this. + +### Verified block state +In the L2 chain, a block is not considered truly final once it is proven; it must also be **verified**. Verification ensures that a block is not only proven but also part of a fully validated sequence of blocks. This requirement arises because blocks can be proposed and proven asynchronously. For instance, if block N has been proven, but its parent block N-1 has not yet been verified, block N cannot achieve the verified status. The verified state is crucial for the protocol as certain operations can only be performed on verified blocks (e.g., mpt verification of state proofs). + +Practically speaking, in order for a block to be considered **verified** it must meet the following conditions: +- The block itself is proven: its cryptographic proof has been submitted and validated by the L1 contract. +- Its parent block is also verified: This guarantees a continuous and valid chain back to the genesis block, which is inherently verified. + +![Block states](/img/rollup/block-states.png) diff --git a/docusaurus.config.js b/docusaurus.config.js index 6ed4d0f..83e8afb 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -6,7 +6,7 @@ import katex from 'rehype-katex'; module.exports = { title: "Puffer UniFi Docs", tagline: "Documentation for the Puffer UniFi Rollup", - url: "https://docs.puffer.fi", + url: "https://docs-unifi.puffer.fi", baseUrl: "/", onBrokenLinks: "throw", onBrokenMarkdownLinks: "warn", @@ -118,7 +118,7 @@ module.exports = { docs: { routeBasePath: "/", sidebarPath: require.resolve("./sidebars.js"), - editUrl: "https://github.com/PufferFinance/unifi-docs", + editUrl: "https://github.com/PufferFinance/unifi-docs/tree/main", remarkPlugins: [math], rehypePlugins: [katex], }, diff --git a/sidebars.js b/sidebars.js index 2f1d316..0a4a90d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -20,8 +20,24 @@ const sidebars = { docSidebar: [ "intro", - "move-funds", - "bridge-ui" + { + type: "category", + label: "Protocol", + link: { + type: "generated-index", + }, + collapsed: false, + items: [ + { + type: "doc", + label: "Overview", + id: "protocol/overview", + }, + ] + }, + + "acquire-testnet-tokens", + "bridge-ui", ], developersSidebar: [ { @@ -29,12 +45,28 @@ const sidebars = { label: "Getting started", id: "developers/getting-started/index", }, + { + type: "category", + label: "Concepts", + link: { + type: "generated-index", + }, + collapsed: false, + items: [ + { + type: "doc", + label: "TEE Multi Prover", + id: "developers/concepts/tee-multi-prover", + }, + ] + }, { type: "category", label: "Deploy a Smart Contract", link: { type: "generated-index", }, + collapsed: false, items: [ { type: "doc", @@ -54,6 +86,7 @@ const sidebars = { link: { type: "generated-index", }, + collapsed: false, items: [ { type: "doc", diff --git a/static/img/rollup/based-sequencing.png b/static/img/rollup/based-sequencing.png new file mode 100644 index 0000000..11e839b Binary files /dev/null and b/static/img/rollup/based-sequencing.png differ diff --git a/static/img/rollup/block-states.png b/static/img/rollup/block-states.png new file mode 100644 index 0000000..cf06172 Binary files /dev/null and b/static/img/rollup/block-states.png differ diff --git a/static/img/tee-multi-prover/overview.png b/static/img/tee-multi-prover/overview.png new file mode 100644 index 0000000..3ddb0fb Binary files /dev/null and b/static/img/tee-multi-prover/overview.png differ diff --git a/static/img/tee-multi-prover/workflow.png b/static/img/tee-multi-prover/workflow.png new file mode 100644 index 0000000..c5c3e20 Binary files /dev/null and b/static/img/tee-multi-prover/workflow.png differ