chore(docs): add docusaurus docs (#384)

This PR introduces docusaurus dev docs.

To preview the docs in your browser: 
- visit https://omni-gamma-beige.vercel.app/ 
- or checkout the branch, cd to docs/site, install deps and run `start`

Four main sections are introduced in these docs, and I'm keen to hear
what people think:

1. Learn - target all audiences with general information about Omni
2. Use - target knowledgeable/developer audience with specifics about
how Omni works (curious for comments from Lazar955 corverroos)
3. Develop - target dApp developers seeking to build with Omni (curious
for comments from kevinhalliday jmozah)
4. Operate - target node runners on how to run a validator (curious for
comments from corverroos jmozah)

I'd vouch to release the site in a minimal version quickly, and then
continue improving and editing through the coming days.

@ttarsi seems as if the PR action for commenting the URL I posted in
this description does not have write permissions for PRs. I tried
editing the settings in the settings for the repo but I appear not to be
permissioned to elevate the rights of github actions agents so that it
can perform that commenting part. So that is the reason that CI step is
failing.

task: https://app.asana.com/0/1206208509925075/1206566996089561/f

.github/workflows/ci-docs.yml

@@ -4,12 +4,11 @@ env:
   VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
 on:
   workflow_dispatch:
-  # TODO(dennis): uncomment upon docusaurus site launch
-  # push:
-  #   branches:
-  #     - main
-  #   paths:
-  #     - 'docs/site/**'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/site/**'
 jobs:
   deploy:
     runs-on: ubuntu-latest

.github/workflows/ci-pr-docs.yml

@@ -30,6 +30,10 @@ jobs:
   comment:
     needs: deploy
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
     steps:
       - name: Comment PR with Deployment URL
         uses: actions/github-script@v7

.gitignore

@@ -18,4 +18,8 @@ dist
 # MacOS specific file
 .DS_Store
 
+# Vercel deployment vars (docs)
+.vercel
+
+# Environment vars
 .env

docs/site/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/site/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/site/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/site/docs/archive/finality.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 3
+id: finality
+---
+
+# Fast Finality
+
+One core goal in the design of the Omni Network is to leverage the incredible, globally distributed computing foundation of Ethereum in combination with the best innovations in the industry that excel exactly where Ethereum falls short. Ethereum is the most decentralized Turing complete computing network in existence. This is an objective reality when measured in terms of geographic distribution, cost to attack and ability to recover from attacks. However, it is simply slow. It also lacks frequent finality.
+
+The Omni Network makes a different set of tradeoffs to perfectly complement the core Ethereum network. It is essential that the foundation of the decentralized web operates with the degree of decentralization that Ethereum provides -- the tradeoffs, however, are unacceptable to end users. In order to onboard billions of people from across the world we need finality that happens in seconds, not minutes.
+
+Omni complements the foundation of the Ethereum network through establishing an infrastructure layer across all rollups that consistently achieves finality in seconds. Omni is an attempt to enhance the global decentralized foundation of Ethereum with the latest innovations in crypto. Through relying on Ethereum where it excels, and using frontier innovations where it does not, Omni is able to provide a solution that elegantly marries security with performance.
+
+A blockchain built for mass adoption of Ethereum
+Historically "alternative layer 1" blockchains have competed with Ethereum for users and capital. Omni is designed differently, being a blockchain built specifically to work as part of, and in unison with Ethereum. The Omni Network provides a higher level of abstraction that simplifies the developer and user experience. It is only possible to achieve this in a secure manner by leveraging the Ethereum network and its validator set.

docs/site/docs/archive/permissionless.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 5
+id: permissionless
+---
+
+# Permissionless Expansion
+
+The Omni Network is designed to facilitate permissionless expansion. This is essential in our vision of creating an open and free global economy, but it is also simply pragmatic. In order to provide the most utility to end users, the Omni Network needs a way to be permissionlessly deployed across all rollups. We achieve this through portal contracts.
+
+## Portal Contracts
+
+Portal contracts are solidity contracts that effectively function as the doorway through which actions flows to and from the Omni Network. Given that they are solidity contracts, they can be deployed on any rollup network without requiring anything from the rollup itself. Validators in the Omni Network monitor updates to these contracts and relay these transactions into the Omni computing environment (see: ), and then propagate resulting actions to any relevant rollup.
+
+## Global By Default
+
+This also benefits developers in their ability to reach wider audiences. When designing applications that are global by default (covered in: [Cross-Rollup Programmability](./programmability)) the portal contract design makes it incredibly easy to propagate interfaces for their applications to any rollup they wish it to be available on as these interfaces just link directly into the portal contracts. This makes the process of expanding an application to a new rollup as simple as appending the name of the rollup in a YAML file. This furthers our design goal of building a decentralized application development platform that allows builders to easily access all users, not just those confined within a single rollup.

docs/site/docs/archive/programmability.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 4
+id: programmability
+---
+
+# Cross-Rollup Programmability
+
+The Omni Network does not only facilitate communication across rollups -- it also enables programmability across rollups. This is a brand new, incredibly powerful programming paradigm that over time will become the de facto method of decentralized application development. We did not build Omni so that people could just pass messages across rollups, we created Omni to facilitate an entirely new programming paradigm that allows developers to think globally, not locally.
+
+## Global, not local
+
+Below I will enumerate some simple examples of what becomes possible in this new programming paradigm. This is not to illustrate a finite set of new features, this is to help you as the reader understand the power of a Turing complete programming interface which has global awareness of all rollups and the ability to directly update those rollups itself.
+
+## Simple Message Passing
+
+This is the boring use case. A majority of readers are likely familiar with this as it does not require programmability and is the functionality offered by simple interoperability protocols like LayerZero.
+
+Example: Alice is on Arbitrum where she has 1 $ETH. She sends that $ETH to Optimism using a simple message passing protocol. Now Alice has 1 $ETH on Optimism.
+
+This is important functionality -- however, it is largely commoditized and uninteresting for modern application development. Our perspective is that users should never have to think about low level operations like this. Developers should build applications that abstract away this complexity from end users. This lowers friction for users and gives developers a greater addressable market as their apps will be default accessible everywhere.
+
+## Dynamic Routing
+
+Expanding beyond what has been previously possible - let's imagine that a developer wished to create a global margin account protocol. The aim of this global margin account would be to allow a user to control their perpetual future positions on $GMX, collateralize lending positions on Optimism, and mint stablecoins on Polygon's zkEVM.
+
+With today's simple message passing protocols, this would be an incredibly arduous process to maintain. Due to risk of liquidation, users would need to consistently monitor their positions in each location, bridge funds to each, and top up their collateral accounts in case they are approaching liquidation. Through Omni this all can be abstracted away into a single transaction.
+
+Instead of monitoring each position, a user can make a simple transaction stating "Ensure I am collateralized at least 200% on my perp, lending and stablecoin positions across all rollups." This transaction would then automatically be picked up by the Omni Network. Instead of passing a static message along, Omni can run custom logic to decide on how many messages get passed, the parameters inside those messages, and where those messages go alongside an automation protocol like Gelato or Autonomy.
+
+Concretely - let's imagine the user is collateralized 300% on their stablecoin position, 190% on their  GMX position and 130% on their lending position. The Omni Network could automatically run logic to understand nothing needs to be done on the stablecoin position, but funds should be topped up on the GMX and lending collateral accounts. It could then programmatically compute the amount that needs to be sent to Arbitrum and Optimism to reach 200% collateralization on these positions and dynamically route messages to these rollups updating the positions to reflect the user request.
+
+In this process the user made a single transaction - the Omni Network took care of the rest.
+
+## Global By Default
+
+Taking this to its logical conclusion we arrive at a place where all apps are global by default. A "global by default" programming paradigm reduces UX friction without compromising on functionality. In addition, it substantially expands the addressable market of users for developers building applications.
+
+_Simple example:_ A developer wishes to conduct an NFT mint. They have built a strong community and would like to set a cap of 10,000 mints. Why would they ever limit themselves to a single rollup and their users? With Omni, now they can conduct their NFT mint in a "global by default" fashion where all of the users across the entire Ethereum ecosystem can participate, substantially expanding their likelihood of success. This is a simple, yet illustrative example of the power of this programming paradigm.
+
+_More powerful example:_ The power of this is even more clear when you consider applications which depend on network effects. Lending markets are a great example - the greater the supply, the cheaper it is to borrow. Through building a lending market that is global by default, there is a clear opportunity to aggregate liquidity across all rollups, creating the largest supply side in the ecosystem and therefore the cheapest borrow rates. This also improves the borrower experience beyond just cost. In this scenario a user would not be confined to borrow within the confines of the rollup where they created their collateral account. They could post collateral on Arbitrum and borrow on zkSync.
+
+Applications that are global by default will outcompete siloed applications over time due to their inherent economic advantages. If you are interested in taking advantage of this property to build a new protocol, please join our Discord to access further resources and meet other builders in the ecosystem.

docs/site/docs/archive/restaking.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 2
+id: restaking
+---
+
+# ETH Restaking
+
+Omni provides a missing, yet essential, infrastructure layer for Ethereum's rollup centric future. This is why, when designing the Omni Network, we asked ourselves "What would be the best way to empower developers to build applications across all rollups if it was part of the core Ethereum protocol?" The answer to this question is to utilize restaking, creating an auxiliary network consisting of existing Ethereum validators who assume additional responsibilities to facilitate this functionality.
+
+Omni sources a global worldview of all rollup state through the coordination of restakers who participate in a set of consensus rules. In order to be eligible to participate in consensus of the network, the validators must stake $ETH so that they have capital at stake that can be slashed in the event that they misbehave and do not follow the agreed upon consensus rules of the network.
+
+## Restaking as a concept
+
+The Omni validators actually "restake" their $ETH -- meaning that they can simultaneously participate in consensus both for the core Ethereum network alongside the Omni network. This concept was invented by the team at EigenLayer and it is a mechanism that allows validators to increase their rewards, while simultaneously opening up an entirely new class of networks like Omni to be formed that further expand functionality of Ethereum network in a way that could not be achieved just through the deployment of smart contracts.
+
+The creation of auxiliary networks that expand the functionality of Ethereum clearly presents great value to the ecosystem of Ethereum developers, but it also empowers the creators of these auxiliary networks with an opportunity to use a credibly neutral, difficult to manipulate and large market cap token as a form of pure collateral to bootstrap new networks.
+
+## How Omni uses restaking
+
+Omni Validators restake $ETH in order to join the list of nodes that participate in the operation of the network. Upon restaking their capital, it is in their best interest to follow the outlined rules of consensus. If they do not, their $ETH will be slashed and they will lose money. If they participate as expected, they will earn rewards through transaction fees submitted to the network. Therefore, through leveraging restaking we have a way to coordinate entities across the world who do not need to know or trust one another to all operate software in a way that provides a net societal benefit. Let's walk through a simple example.
+
+Alice has $100 worth of $ETH on Arbitrum and would like to borrow some $USDC against that position to buy a token for a new project that just launched on Optimism. Using Omni, she could escrow her funds on Arbitrum, have that confirmation relayed to Optimism, and borrow $50 on Optimism while using her $100 of $ETH on Arbitrum as collateral. Alice can now use that $50 to invest in the new project that she is excited about.
+
+This is a simple, yet illustrative example of the power of Omni -- especially because this can be abstracted away from Alice. She might not care about which rollup her money is on, she might just want to participate in the decentralized web and Omni allows application developers to abstract all this away from end users to give them the best experiences the crypto industry has to offer without burdening them with technical requirements.
+
+The way that the Omni Network secures this transition of data from Arbitrum to Optimism is restaking. The validators in the network would be monitoring Arbitrum and see Alice's transaction. It is in all of their interest to truthfully report the data of this transaction and they will do this by signing a statement declaring their view on this transaction that can be associated with their address that has restaked $ETH. If they lie, ultimately Arbitrum will post this data to layer 1 Ethereum and then anybody will be able to take the false, yet signed statement by a dishonest validator, submit it to the restaking contract and slash the dishonest validator.
+
+Validators restake $ETH and attest to state updates that happen in rollups. They are incentivized to participate in this network through rewards that manifest from transaction fees. They are disincentivized from lying because ultimately the truth of all data will be posted down from rollups to layer 1 Ethereum where the validator will have their restaked $ETH slashed. It is simple, elegant, and scalable.
+
+This is how the Omni Network is secured. The simplicity is intentional. We are building a network to secure the future of the crypto industry. There is no space for convoluted data structures, complex multi-agent interactions or third party dependencies. This is the only model that can keep pace as we onboard hundreds of millions of people across the world into an open, permissionless economy.