Merge pull request #36 from NilFoundation/nil-initial

Nil initial

Author: khannanov-nil

.vscode/settings.json

@@ -3,6 +3,10 @@
         {
             "language": "mdx",
             "scheme": "file"
+        },
+        {
+            "language": "markdown",
+            "scheme": "file"
         }
     ]
 }

docusaurus.config.js

@@ -82,10 +82,10 @@ const config = {
     [
       '@docusaurus/plugin-content-docs',
       {
-        id: 'zksharding',
-        path: 'zksharding',
-        routeBasePath: 'zksharding',
-        sidebarPath: './sidebars.js'
+        id: 'nil',
+        path: 'nil',
+        routeBasePath: 'nil',
+        sidebarPath: './sidebar-nil.js'
       }
     ],
   ],
@@ -126,8 +126,8 @@ const config = {
             },
             {
               position: 'left',
-              label: 'zkSharding',
-              to: 'https://nil.foundation/blog/post/nil_zkSharding'
+              label: '=nil;',
+              to: '/nil/intro'
             },
             {
               position: 'left',

nil/intro.mdx

@@ -0,0 +1,36 @@
+import Thesis from '@site/static/img/nil/nil-icons/thesis.png'
+import Principles from '@site/static/img/nil/nil-icons/principles.png'
+import {Card, CardSection} from '@site/src/components/CardSection'
+
+# Overview
+
+## Definition
+
+=nil; is a sharded blockchain that leverages the following features:
+
+* **Modularity**. =nil; offers an execution layer while using Ethereum for data availability and consensus.
+* **Horizontal scalability**. In =nil;, execution is spread across shards, allowing for completing tasks in parallel.
+* **Vertical scalability**. Validator implementation in =nil; is scaled vertically via intra-shard parallelization.
+
+=nil; offers an effective strategy for scaling Ethereum while avoiding the limitations typically associated with the modular approach such as state and liquidity fragmentation.
+
+:::tip[Why =nil;?]
+
+As =nil; is highly scalable, it is ideal for applications that are demanding in terms of algorithm complexity, or time and memory usage:
+
+* Crowdsourcing platforms
+* Autonomous virtual worlds
+* Decentralized exchanges
+
+:::
+
+## Structure of the Documentation
+
+### Introduction
+
+Learn the basics of what =nil; is and how it works.
+
+<CardSection>
+    <Card icon={<img src={Thesis}/>} id='thesis' title='Thesis' description='Read about the "how" and "why" of =nil;' to='./thesis'/>
+    <Card icon={<img src={Principles}/>} id='principles' title='Principles' description='Grasp the fundamentals of the architecture of =nil;' to='./principles'/>
+</CardSection>

nil/principles.mdx

@@ -0,0 +1,46 @@
+import Flows from '@site/static/img/nil/flows.png'
+
+# Thesis
+
+This page explains the rationale behind the architecture of =nil; and provides insight into how =nil; resolves the fundamental monolithic vs. modular dispute.
+
+## Problem statement
+
+The rollup-centric roadmap to scaling Ethereum and the rise in the popularity of rollups introduced a significant issue: state fragmentation.
+
+State fragmentation means that parts of Ethereum's global state are effectively scattered across systems that are distinct from Ethereum itself. This leads to the following outcomes:
+
+* Liquidity and users are spread across various networks all of which have a unique infrastructure
+* Cross-network operations being difficult to secure, resulting in more hacks
+* Worsened developer and user experience. It falls either on developers or users to ensure cross-chain operations which adds an unnecessary layer of complexity
+
+The architecture of =nil; is designed specifically to resolve these issues. 
+
+## Solution
+
+Instead of focusing on improving interoperability (which only produces a 'bandaid' fix to the fragmentation problem), the goal of =nil; is to maximise scalability.
+
+=nil; achieves this by integrating both horizontal and vertical scaling supported by zkSharding.
+
+:::info[Definitions]
+
+**Horizontal scaling** refers to improving the throughput of a chain by adding more nodes. 
+
+**Vertical scaling** is improving the throughput of a chain by upgrading the capacity of existing nodes or upgrading hardware utilization.
+
+**zkSharding** is a type of sharding architecture in which the shards responsible for execution algo generate zero-knowledge proofs (ZKP) verifying intra-shard state transitions. There is also a dedicated shard for coordinating execution shards and communicating with Ethereum.
+
+:::
+
+zkSharding allows for combining horizontal and vertical sharding within the scope of one sharded network.
+
+* More shards can be added as needed without compromising security
+* Nodes in a shard can employ parallelized VMs for vertical intra-shard scaling
+
+Cross-shard communications are incorporated directly into the =nil; protocol. This means that the issue of fragmentation is avoided entirely as each shard can call contracts deployed on a different shard via transactions verified through ZKP.
+
+## Flows
+
+The following diagram shows how =nil; organizes execution shards, the main shard, the transfer of ZKPs, and communications with Ethereum.
+
+<img src={Flows}/ >

nil/thesis.mdx

@@ -0,0 +1,28 @@
+export default {
+    nil: [
+        {
+            type: 'category',
+            label: 'Introduction',
+            collapsed: false,
+            collapsible: true,
+            items: [
+                {
+                    type: 'doc',
+                    label: 'Overview',
+                    id: 'intro',
+                },
+                {
+                    type: 'doc',
+                    label: 'Thesis',
+                    id: 'thesis'
+                },
+                {
+                    type: 'doc',
+                    label: 'Principles',
+                    id: 'principles'
+                }
+            ]
+        },
+
+    ]
+}

sidebar-nil.js

@@ -0,0 +1,80 @@
+import React, { ReactNode, PropsWithChildren } from 'react';
+import Link from '@docusaurus/Link';
+import clsx from 'clsx';
+
+export function CardSection({
+  id,
+  title,
+  children,
+  description,
+  className,
+  hasSubSections = false,
+  HeadingTag = 'h3',
+}: {
+  id?: string;
+  title: string;
+  children: ReactNode;
+  description?: ReactNode;
+  hasSubSections?: boolean;
+  HeadingTag?: keyof JSX.IntrinsicElements;
+  className?: string;
+}) {
+  return (
+    <div
+      className={clsx(
+        'homepage-section',
+        hasSubSections && 'has-sub-sections',
+        className
+      )}
+    >
+      {title && <HeadingTag id={id ?? title}>{title}</HeadingTag>}
+      {description && <p className="section-description">{description}</p>}
+      <div className="section-content">{children}</div>
+    </div>
+  );
+}
+
+export function Card({
+  id,
+  icon,
+  title,
+  description,
+  to,
+  tag,
+  className,
+}: PropsWithChildren<{
+  id?: string;
+  icon?: JSX.Element;
+  title: string;
+  description?: string;
+  to: string;
+  tag?: {
+    label: string;
+    color: string;
+    description: string;
+  };
+  className?: string;
+}>) {
+  return (
+    <Link to={to} className={clsx("homepage-card",className)}>
+      {icon && <div className="icon">{icon}</div>}
+      <div className="card-content">
+        <div className="title" id={id && title}>
+          {title}
+        </div>
+        {description && <div className="description">{description}</div>}
+      </div>
+      {tag && (
+        <div className="tag absolute right-0 top-0 h-16 w-16">
+          <span
+            className="absolute right-[-28px] top-[-2px] w-[80px] rotate-45 transform bg-gray-600 py-1 text-center font-semibold text-white"
+            style={{ backgroundColor: tag.color }}
+            title={tag.description}
+          >
+            {tag.label}
+          </span>
+        </div>
+      )}
+    </Link>
+  );
+}

src/components/CardSection/index.tsx

@@ -31,9 +31,10 @@ const ProductsList =
       image: zkSharding,
       description: (
         <>
-          <p>=nil; zkSharding is the first Ethereum zkRollup with sharding — an alternative to the current Ethereum scalability ecosystem.</p>
-          <p>The unique combination of zkRollup and sharding enables secure and parallel transaction execution across dedicated shards while maintaining Ethereum's economic security and providing application developers with full composability and transparent data access.</p>
+          <p>=nil; is a sharded blockchain that resolves Ethereum scalability issues via zkSharding.</p>
+          <p>=nil; aims to achieve global scale without state, liquidity or user fragmentation.</p>
           <p><a href="https://nil.foundation/blog/post/nil_zkSharding">https://nil.foundation/blog/post/nil_zkSharding</a></p>
+          <p>Documentation, tutorials and recipes for application developers, proof producers, and validators.</p>
         </>
       ),
     },
@@ -95,7 +96,7 @@ export default function HomepageNilProducts() {
       <div className={'row' + ' ' + styles.rowFlex}>
         <div className='col col-6'>
           <div id='zk-sharding-docs'>
-            <NilProduct image={ProductsList[2].image} description={ProductsList[2].description} onDocsClick={GoToDocs("https://nil.foundation/blog/post/nil_zkSharding")}></NilProduct>
+            <NilProduct image={ProductsList[2].image} description={ProductsList[2].description} onDocsClick={GoToDocs("/nil/intro")}></NilProduct>
           </div>
         </div>
         <div className='col col-6'>