Add documentation for Vara Bridge

docs/bridge/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Vara Bridge",
+    "position": 13
+}

docs/bridge/architecture.md

@@ -0,0 +1,149 @@
+---
+title: Bridge Architecture
+sidebar_position: 3
+sidebar_label: Bridge Architecture
+---
+
+# Bridge Architecture
+
+## Overview
+This page provides a technical overview of the Vara Bridge architecture, without covering every component in exhaustive detail. The goal is to give readers a high-level understanding of how the Bridge operates. For complete technical information, please refer to the [Gear Bridges repository](https://github.com/gear-tech/gear-bridges).
+
+Vara Bridge uses Plonky2 circuits to implement cryptographic primitives, forming a secure foundation for cross-chain operations. Plonky2 is a zero-knowledge (ZK) proof system that provides efficient and scalable proofs. By using these circuits, Vara Bridge preserves transaction integrity and greatly reduces the possibility of manipulation. The proof mechanism also guarantees that specific pallet states are finalized and included in the Vara Network before those states are relayed to Ethereum. Verified within a Gnark circuit, these proofs help maintain trust and accuracy as data moves across chains.
+
+## Bridge Components
+The Vara Bridge consists of several distinct parts, including on-chain components on both Vara and Ethereum, as well as off-chain components for securely relaying message proofs.
+
+### Components on Vara Network
+
+- **VFT programs**: Deployments of the [VFT token standard](/docs/build/standards/vft), capable of transferring, burning, and minting VFT tokens. Each unique token has its own VFT deployment on Vara.
+
+- **VFT Manager**: A single program that receives VFT tokens from users, burns them, and emits a message to the `pallet-gear-eth-bridge` Built-in actor. This message indicates which token is being bridged, the token amount, and the intended Ethereum recipient.
+
+- **Bridging Built-in Actor**: A new Built-in Actor serving as the entry point for the generic bridging protocol. It takes messages from any actor on the Vara Network and forwards them to the Bridging pallet.
+
+- **Bridging Pallet**: Accepts messages from the Bridge Built-in Actor and stores them in specialized data structure (a binary Merkle trie).
+
+- **Ethereum-Event-Client**: A program on Vara that verifies whether a specific event emitted by an Ethereum smart contract was included in a particular block. It consults the `checkpoint-light-client` to confirm the validity of that block.
+
+- **Historical-Proxy**: A program on Vara that maintains historical `ethereum-event-client` program addresses and routes requests to the `ethereum-event-client` instance responsible for processing the requested transaction.
+
+- **Checkpoint-Light-Client**: A lazy Ethereum light client that keeps track of the `sync committee` validator set and confirms block headers using it.
+
+### Components on Ethereum
+
+- **ERC20Manager**: Implements the `IMessageQueueReceiver` interface and functions as a vault for ERC-20 tokens, permitting users to deposit tokens and manage withdrawals. It processes messages relayed by the `MessageQueue` and accepts only properly formatted and authorized messages.
+
+- **MessageQueue**: Verifies proofs of message inclusion in a Merkle trie, whose root is stored in the `Relayer`. It ensures each message is processed exactly once by storing nonces for all of the processed messages. After successful verification, it calls the target `IMessageQueueReceiver` contract (e.g., `ERC20Manager`).
+
+- **Relayer**: Although historically referred to as the `Relayer`, this component is actually an on-chain contract on Ethereum. It receives a Merkle trie root proof from the Prover and submits it to the `Verifier` for validation via `PlonkVerifier`. Once the proof is confirmed, the contract records the validated Merkle trie root and block number, enabling the `MessageQueue` to authenticate messages.
+
+- **Verifier**: Uses a `PlonkVerifier` to check Gnark proofs confirming that a given Merkle trie root matches the one specified in the proof for a finalized Vara block. By validating this match, the `Verifier` ensures the bridging process proceeds with correct state data.
+
+### Components on Both Networks
+
+- **Bridging Payment**: Implemented as a Program on Vara and as a smart contract on Ethereum, both versions have the same functions. When a bridging request is received, they charge fees and pass the request to the respective smart contract/program that executes it. A token relayer can then monitor events indicating the request has been processed (and fees paid) and finalize the request on the other chain, using its own funds to pay transaction fees.
+
+### Off-Chain Components
+In addition to the on-chain components, there are relayer nodes responsible for transferring data between Vara and Ethereum:
+
+- **Vara→Ethereum Protocol relayer**: Reads the Vara state, creates ZK proofs, and sends them to Ethereum. It produces two kinds of ZK proofs:  
+  - Proof of authority set changes  
+  - Proof of Merkle trie root inclusion in the `pallet-gear-eth-bridge` storage
+
+- **Ethereum→Vara Protocol relayer**: Tracks `sync committee` changes and the blocks they sign on Ethereum. It then updates the `checkpoint-light-client` state on Vara.
+
+- **Ethereum→Vara Token relayer** and **Vara→Ethereum Token relayer**: Monitor events from `bridging-payment` services and handle cross-chain actions to ensure messages are delivered correctly.
+
+## Proof Generation and Verification
+The Ethereum smart contracts handle messages and their proofs originating from Vara Network. On Vara, each message is kept in a binary Merkle trie. The Merkle root of this trie—a concise, verifiable representation of all messages—is recorded in the `pallet-gear-eth-bridge` storage. This setup guarantees that messages can be thoroughly verified when they reach Ethereum. The `Prover` component generates a zero-knowledge proof (ZK proof) indicating that a given Merkle trie root is stored in the pallet’s storage at a particular finalized block. This proof is then sent to Ethereum.
+
+In the Vara Bridge, the `Prover` component is carried out by the `Vara→Ethereum relayer`, which enables trustless relaying of Merkle trie roots from the `pallet-gear-eth-bridge` to Ethereum.
+
+Proof creation relies on **proof composition**, in which proofs are generated and verified before being merged into higher-level proofs. It also incorporates **recursive proofs** that use IVC (Incrementally Verifiable Computation). This approach breaks the computation into incremental steps and proves them iteratively, for example, updating the validator set from genesis to the latest block.
+
+
+## Token Transfer Workflows
+### From Vara Network to Ethereum
+
+From a broad standpoint, the user starts a bridging request in the frontend, giving the bridge permission to spend the specified tokens. After deducting any necessary fees, the bridging process leads to the burning of tokens on Vara Network, producing a message. This message is relayed by the Built-in actor and stored in Vara’s storage. Subsequently, an off-chain relayer forwards this message to the Ethereum relayer contract. Once the Merkle proof is validated, the ERC-20 Manager releases the corresponding funds to the user on Ethereum.
+
+```mermaid
+flowchart LR
+
+    direction LR
+    subgraph V["Vara Network"]
+        direction TB
+        BP["bridging-payment"]:::varaStyle --"Bridging request"--> VM["VFT Manager"]:::varaStyle;
+        VM["VFT Manager"] --"Store request in storage"--> PGEB["pallet-gear-eth-bridge"]:::varaStyle;
+    end
+
+
+    subgraph VER["Vara->Eth Relayer"]
+        direction TB
+    end
+
+        subgraph VERT["Vara->Eth Token Relayer"]
+        direction TB
+    end
+
+    subgraph ETH["Ethereum"]
+        direction TB
+        RL["Relayer contract"]:::varaStyle;
+        MQ["MessageQueue contract"]:::varaStyle--> EM["ERC20Manager contract"]:::varaStyle;
+        RL--"Submits Merkle trie root<br>proof for validation"-->VF["Verifier contract"]:::varaStyle;
+        VF--"Confirms/rejects proof"-->RL
+
+  end
+  U1["User"]:::varaStyle --"Requests bridging<br> via frontend"---> V:::varaStyle;
+  V --> VER
+  VER --"Store Merkle Trie root<br>in Relayer contract"-->ETH:::varaStyle;
+  VERT --"Listen for Merkle trie roots in<br> Relayer contract and forward <br> bridging request to MessageQueue"-->MQ
+  EM--"Release funds"-->U2["Recipient"]:::varaStyle;
+
+classDef Vara stroke:#00ffa0,stroke-width:3px;
+classDef varaStyle stroke:#00ffc3;
+classDef plain stroke:#FFFFFF;
+```
+
+1. **Transfer Initiation**  
+   The user starts a bridging request in the Bridge frontend, permitting the `VFT Manager` to spend the user’s tokens.
+
+2. **Token Burning on Vara**  
+   The `VFT Manager` burns the tokens on Vara Network and sends a message to initiate bridging. This message goes to the Bridge Built-in Actor, which forwards it to the `pallet-gear-eth-bridge`.
+
+3. **Inclusion in Pallet Storage**  
+   The `pallet-gear-eth-bridge` places the message into a specialized binary Merkle trie.
+
+4. **Proof Generation and Transmission**  
+   The `Vara→Ethereum relayer` reads from `pallet-gear-eth-bridge` storage and produces a zero-knowledge (ZK) proof indicating that the message is included in a finalized Vara block. The relayer submits this proof to Ethereum, storing it in the `Relayer` contract.
+
+5. **Proof Verification on Ethereum**  
+   Prompted by the `Vara→Ethereum Token Relayer`, the `MessageQueue` contract retrieves the Merkle root from the `Relayer` contract. It verifies the Merkle proof and, if successful, passes the message on to the `ERC20Manager`.
+
+6. **Release of Funds**  
+   The `ERC20Manager` releases the tokens to the user’s account on Ethereum.
+
+### From Ethereum to Vara Network
+
+In brief, the user submits a bridging request in the frontend, allowing the bridge to spend the chosen ERC-20 tokens. After fees are deducted, the tokens are locked or burned on Ethereum, triggering an event. An off-chain relayer carries this event to Vara for validation against the Ethereum checkpoint-light-client. After confirmation, the historical-proxy instructs the **VFT Manager** to mint or transfer tokens on Vara, giving the user the equivalent number of tokens. Below is the expanded version:
+
+1. **Transfer Initiation**  
+   The user initiates a bridging request in the Bridge frontend. They authorize the `bridging-payment` contract to spend their ERC-20 tokens by calling `approve` on the relevant ERC-20 contract on Ethereum.
+
+2. **Token Locking/Burning on Ethereum**  
+   After receiving the request, the `bridging-payment` instructs the `ERC20Manager` to lock or burn the ERC-20 tokens. The resulting event signals that these tokens are removed from circulation or escrowed for bridging.
+
+3. **Block Checkpoint and Event Submission**  
+   Once the event is emitted, the `Ethereum→Vara Protocol relayer` (or a similar entity) provides a newer Ethereum block reference (at a block number beyond the burn/lock event) to the `checkpoint-light-client` on Vara. Then, the relayer forwards the event to the `historical-proxy`, which supervises the on-chain validation.
+
+4. **Event Verification**  
+   The `historical-proxy` requests the `ethereum-event-client` to verify that the block containing the burn/lock event is a valid, finalized Ethereum block. The `ethereum-event-client` consults the `checkpoint-light-client` to confirm finality. Once validated, the `historical-proxy` proceeds with bridging.
+
+5. **Bridging on Vara**  
+   Having confirmed the event, the `historical-proxy` sends the user’s bridging request to the `VFT Manager`. The `VFT Manager` calls the suitable `VFT program` for the locked/burned ERC-20 tokens. Depending on the token model:  
+   - **Transfer**: If the total supply resides on Vara, the vft program simply transfers tokens.  
+   - **Mint**: If the token supply is on Ethereum, the vft program mints new tokens on Vara.
+
+6. **Release of Tokens on Vara**  
+   Finally, the `VFT program` either mints or transfers the bridged tokens to the user’s address on Vara, concluding the Ethereum→Vara bridging process.

docs/bridge/bridge.mdx

@@ -0,0 +1,76 @@
+---
+title: Vara Bridge
+sidebar_position: 3
+sidebar_label: Vara Bridge
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Vara Bridge
+
+:::important
+The Vara Bridge is now live for testing between the Vara Testnet and the Ethereum Holesky Testnet. You can try it out [here](https://zk-bridge-stg.vara.network/).
+For updates on the upcoming Vara Bridge mainnet launch, follow [Vara Network on X](https://x.com/VaraNetwork) or check out the [Vara Blog](https://vara.network/news).
+:::
+
+## Introduction
+**Vara Bridge** is a trustless, ZK-based cross-chain bridge designed to transfer tokens and data securely between Ethereum and the Vara Network. It leverages **Plonky2** circuits and zero-knowledge proofs (ZK proofs) to validate transactions without revealing sensitive information. By doing so, Vara Bridge minimizes the risk of manipulation or fraud while delivering efficient cross-chain transfers. 
+
+In short, the bridge unites **Ethereum’s** liquidity and established ecosystem with **Vara Network’s** speed and scalability. This integration expands token liquidity, enables new utilities, and facilitates cross-chain interactions for **VARA** and other tokens deployed on Vara.
+
+---
+
+## Supported Tokens
+We're actively working to add more assets to the bridge, so expect the list of supported tokens to grow in the near future.
+
+<Tabs>
+  <TabItem value="Testnet" label="Testnet" default>
+- **VARA** ([wVARA](https://holesky.etherscan.io/token/0x1ebbdad5274735fd2651d872a25abb19d6b025f0) on Ethereum Holesky)  
+- **WETH** ([WETH](https://idea.gear-tech.io/programs/0x3ddd2d4f64f54926aaf4ca1c75297cac52828c52cd3a4690cc1342606a67d86c?node=wss%3A%2F%2Ftestnet.vara.network) on Vara Testnet)
+
+You can acquire a test balance on Vara Testnet by following the steps [here](docs/idea/account.md#get-test-balance).
+</TabItem>
+  <TabItem value="Mainnet" label="Mainnet" default>
+  Coming soon.
+  </TabItem>
+</Tabs>
+
+## Key Benefits of Vara Bridge
+
+### For the VARA Token
+By enabling **wrapped VARA (wVARA)** on Ethereum, the bridge introduces a critical avenue for growth and utility:
+
+- **Enhanced Liquidity**  
+  - Listing wVARA on popular Ethereum DEX platforms (e.g., Uniswap, Balancer, SushiSwap, HyperLiquid).  
+  - Potential listings on centralized exchanges that support Ethereum-based assets.  
+  - Broader exposure to Ethereum’s DeFi infrastructure.
+
+- **New Utility**  
+  - **Staking/Restaking:** Users can stake or restake wVARA (e.g., in Symbiotic) to earn rewards while helping secure Gear.exe computations.  
+  - **Operator Rewards:** Node operators running Gear.exe gain additional incentives, creating a more robust and high-performance network.
+
+Ultimately, bridging VARA to Ethereum expands the token’s financial flexibility, market visibility, and collaborative opportunities.
+
+### For Projects on Vara
+Projects and dApps built on Vara benefit significantly from tapping into Ethereum’s user base and liquidity:
+
+- **Access to New Users and Capital**  
+  - Instantly reach Ethereum’s extensive DeFi ecosystem, liquidity pools, and yield-farming platforms.
+
+- **Cross-Chain Opportunities**  
+  - Deploy dApps that communicate seamlessly between Vara and Ethereum (e.g., Invariant, Guardian Protocol, VarSwap).  
+  - Create Vara-based tokens that can also be listed or traded on Ethereum DEXs.
+
+- **Simplified Token Listings**  
+  - Project tokens originating on Vara can leverage top-tier Ethereum DEXs and existing tooling with minimal friction.  
+
+By bridging to Ethereum, Vara-based projects gain broader user engagement, increased capital flow, and enhanced cross-chain functionality.
+
+## Next Steps
+
+### How to Bridge
+For a step-by-step guide on transferring tokens between Vara and Ethereum, see the [**Use Vara Bridge**](/docs/bridge/bridging-guide.md) page.
+
+### Technical Architecture
+For a deeper dive into how the bridge works under the hood, check out the [**Bridge Architecture**](/docs/bridge/architecture.md) page.

docs/bridge/bridging-guide.md

@@ -0,0 +1,83 @@
+---
+title: Use Vara Bridge
+sidebar_position: 2
+sidebar_label: Use Vara Bridge
+---
+
+# Use Vara Bridge
+This page provides a guide on bridging supported VFT tokens from Vara Network to their corresponding wrapped ERC-20 tokens on Ethereum, and vice versa.
+
+## Prerequisites
+
+- A Substrate wallet (for example, [**SubWallet**](https://www.subwallet.app/))
+- An Ethereum wallet (for example, [**MetaMask**](https://metamask.io/))
+
+---
+
+## Bridging from Vara Network to Ethereum
+
+:::tip
+This tutorial uses Vara's Testnet and **TVARA** tokens. You can acquire a test balance by following the steps [here](docs/idea/account.md#get-test-balance).
+:::
+
+![vara-bridge](img/vara_bridge_tutorial_snap01.png)
+
+1. **Connect Your Wallet**  
+   Connect your Substrate wallet to the Vara Bridge.
+
+2. **Select the Token to Transfer**  
+   Choose **TVARA** from the dropdown menu and specify the number of tokens to transfer.
+
+3. **Enter the Receiving Ethereum Address**  
+   In the next field, provide a valid ERC-20 address on Ethereum Holesky where you want the tokens sent.
+
+4. **Initiate the Bridging Process**  
+   Click **Transfer** to start bridging. The bridging fee and estimated transfer time are displayed above the button.
+
+![vara-bridge](img/vara_bridge_tutorial_snap02.png)
+
+5. **Sign and Approve**  
+   Confirm the transfer of your tokens in your wallet.
+
+![vara-bridge](img/vara_bridge_tutorial_snap03.png)
+
+After initiating the transfer, your bridging transaction appears in the list of all transactions. When the process completes, the status changes from **pending** to **completed**.
+
+![vara-bridge](img/vara_bridge_tutorial_snap04.png)
+
+:::note
+After sending tokens from Vara to Ethereum, you may need to manually add the **VARA token contract** to your Ethereum wallet to view your updated balance.
+:::
+
+---
+
+## Bridging from Ethereum to Vara Network
+
+:::tip
+This walkthrough also uses Vara’s Testnet and **TVARA** tokens. To start bridging to the Vara Testnet, you will need a small **ETH** balance on Ethereum Holesky.
+:::
+
+![vara-bridge](img/vara_bridge_tutorial_snap05.png)
+
+1. **Connect Your Wallet**  
+   Connect your Ethereum wallet to the Vara Bridge.
+
+2. **Select the Token to Transfer**  
+   Choose **WVARA** from the dropdown and specify how many tokens you want to bridge.
+
+3. **Enter the Receiving Vara Address**  
+   In the next field, provide a valid **Vara** address where the tokens will be delivered.
+
+4. **Initiate the Bridging Process**  
+   Click **Transfer** to begin bridging. The fee and estimated transfer time appear above the button.
+
+![vara-bridge](img/vara_bridge_tutorial_snap06.png)
+
+5. **Sign and Approve**  
+   Authorize the transfer of your tokens in your Ethereum wallet.
+
+![vara-bridge](img/vara_bridge_tutorial_snap07.png)
+
+After the transaction is submitted, your bridging request appears in the transaction list. When the bridging is complete, its status changes from **pending** to **completed**. This can take up to 20 minutes.
+
+![vara-bridge](img/vara_bridge_tutorial_snap08.png)

package.json

@@ -59,5 +59,6 @@
   },
   "engines": {
     "node": ">=18"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }