manual mirror done (#126)

Author: khannanov-nil

.gitignore

@@ -18,3 +18,6 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+/.github
+/.husky

README.md

@@ -41,7 +41,7 @@ There exist four separate sets of docs contained in the following folders.
 * `./nil`
 * `./crypto3`
 
-All four sets of docs are rendered as a single React app configured in `docusaurus.config.js`.
+Note that only =nil; docs are rendered when running the Docusaurus instance. The rest only exist as collections of raw `.md` files.
 
 # Contributing
 

babel.config.js

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

docs/api/index.md

@@ -1,16 +1,3 @@
 # Documentation Repository for =nil;
 
-This repository is the host of the Docusaurus project that handles documentation for =nil; Foundation. 
-
-# Structure
-
-The project follows the monorepo pattern to simplify dependency management.
-
-There exist four separate sets of docs in the following folders.
-
-* `./zkllvm`
-* `./proof-market`
-* `./zksharding`
-* `./crypto3`
-
-Each set of docs is connected to a single React app which is configured in the `docusaurus.config.js` file.
+This repository is the host of the Docusaurus project that handles documentation for =nil;. 

docs/api/typedoc-sidebar.cjs

@@ -1,4 +1,4 @@
 // @ts-check
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const typedocSidebar = { items: []};
-module.exports = typedocSidebar.items;
+const typedocSidebar = { items: [] };
+module.exports = typedocSidebar.items;

docusaurus.config.js

@@ -8,6 +8,7 @@ import { themes as prismThemes } from 'prism-react-renderer';
 
 import remarkMath from 'remark-math';
 import rehypeKatex from 'rehype-katex';
+import remarkCodeSnippets from 'nil-remark-code-snippets';
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -26,8 +27,9 @@ const config = {
   organizationName: '=nil; Foundation', // Usually your GitHub org/user name.
   projectName: 'docs.nil.foundation', // Usually your repo name.
 
-  onBrokenLinks: 'throw',
+  onBrokenLinks: 'log',
   onBrokenMarkdownLinks: 'warn',
+  onBrokenAnchors: 'log',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -46,10 +48,10 @@ const config = {
           path: "nil",
           routeBasePath: "nil",
           sidebarPath: require.resolve("./sidebar-nil.js"),
-          remarkPlugins: [remarkMath],
+          remarkPlugins: [remarkMath, remarkCodeSnippets],
           rehypePlugins: [rehypeKatex],
           openrpc: {
-            openrpcDocument: "https://api.devnet.nil.foundation/api/docs/openrpc.json",
+            openrpcDocument: process.env.OPENRPC_JSON,
             path: "references",
             sidebarLabel: "JSON-RPC API",
           },
@@ -68,43 +70,17 @@ const config = {
     'docusaurus-plugin-goatcounter'
     ,
     [
-      '@docusaurus/plugin-content-docs',
-      {
-        id: 'zkllvm',
-        path: 'zkllvm',
-        routeBasePath: 'zkllvm',
-        sidebarPath: './sidebar-zkllvm.js'
-      }
-    ],
-    [
-      '@docusaurus/plugin-content-docs',
-      {
-        id: 'proof-market',
-        path: 'proof-market',
-        routeBasePath: 'proof-market',
-        sidebarPath: './sidebar-proof-market.js'
-      }
-    ],
-    [
-      '@docusaurus/plugin-content-docs',
-      {
-        id: 'crypto3',
-        path: 'crypto3',
-        routeBasePath: 'crypto3',
-        sidebarPath: './sidebar-crypto-3.js'
-      }
-    ],
-    [
-      'docusaurus-plugin-typedoc',
+      'nil-docusaurus-plugin-typedoc',
       {
         out: "./nil/reference/client",
         outputFileStrategy: "members",
         fileExtension: ".mdx",
         useCodeBlocks: true,
         parametersFormat: "htmlTable",
         entryPoints: [
-          "./nil/nil.js/src"
+          'node_modules/@nilfoundation/niljs/dist/niljs.cjs'
         ],
+        tsconfig: `tsconfig.json`,
         skipErrorChecking: true,
         sidebar: {
           "autoConfiguration": true,
@@ -160,26 +136,47 @@ const config = {
           },
           items: [
             {
+              label: 'Documentation',
               position: 'left',
-              label: '=nil;',
               to: '/nil/intro'
             },
             {
+              label: 'Cookbook',
               position: 'left',
-              label: 'zkLLVM',
-              to: '/zkllvm/overview/what-is-zkllvm'
-
+              to: '/nil/cookbook'
             },
             {
+              label: 'Migration guides',
               position: 'left',
-              label: 'Proof Market',
-              to: '/proof-market/intro'
+              to: 'nil/migration-guides/september-1709-2024-release'
             },
             {
-              position: 'left',
-              label: 'Crypto3',
-              to: '/crypto3/intro'
-            },
+              type: 'dropdown',
+              label: 'Developer tools',
+              position: 'right',
+              items: [
+                {
+                  label: 'Block explorer',
+                  href: 'https://explore.nil.foundation/'
+                },
+                {
+                  label: 'Solidity extension',
+                  href: 'https://github.com/NilFoundation/nil_cli/blob/master/Nil.sol'
+                },
+                {
+                  label: '=nil; CLI',
+                  href: 'https://github.com/NilFoundation/nil_cli/tree/master'
+                },
+                {
+                  label: 'Client library',
+                  href: 'https://www.npmjs.com/package/@nilfoundation/niljs'
+                },
+                {
+                  label: 'Hardhat plugin',
+                  href: 'https://github.com/NilFoundation/nil-hardhat-example'
+                }
+              ]
+            }
           ],
         },
         footer: {
@@ -214,4 +211,4 @@ const config = {
       }),
 };
 
-export default config;
+export default config;

nil/cookbook/index.mdx

@@ -0,0 +1,17 @@
+import {CookbookCard, CookbookCardSection, CookbookBadges} from '@site/src/components/CookbookCardSection';
+
+# Create a swap contract and custom tokens
+
+This series of recipes show how to create a swap contract that can reliably exchange one custom currency with another even if the contracts representing these currencies are located on different shards. 
+
+The swap contract adopts order book-like mechanics by matching swap requests from different wallets. When requests are matched, the contract processes them and takes care of any excess tokens by sending them back to the request originators.
+
+<CookbookCardSection>
+  <CookbookCard badges={[CookbookBadges[0]]} tag={{
+    label: "8 min read",
+  }} id='swap1' title='Design the swap contract' description='' to='./cookbook/swap/create-swap-contract'
+  />
+  <CookbookCard badges={[CookbookBadges[2]]} tag={{
+    label: "7 min read",
+  }} id='swap2' title='Deploy and test the swap contract' description='' to='./cookbook/swap/deploy-test-swap'/>
+</CookbookCardSection>

nil/cookbook/swap/create-swap-contract.mdx

@@ -0,0 +1,82 @@
+# Create the swap contract
+
+The swap contract needs to do the following:
+
+* Accept swap requests
+* Match swap requests and exchange tokens
+* Handle excess tokens and send them back to wallets located on different shards
+
+## Contract definition
+
+```solidity showLineNumbers
+
+pragma solidity ^0.8.26;
+
+import "@nilfoundation/smart-contracts/contracts/Nil.sol";
+
+/**
+ * @title SwapMatch
+ * @author =nil; Foundation
+ * @notice The contract matches swap requests and performs token swaps.
+ * On a successful match, the desired tokens are sent to the swap originators.
+ * The contract also calculates token excesses and sends them back on a successful match.
+ */
+contract SwapMatch is NilBase {}
+```
+
+## Structs and properties
+
+The contract contains the following structs and properties:
+
+```solidity showLineNumbers file=../../../tests/SwapMatch.sol start=startContractStructsAndProperties end=endContractStructsAndProperties
+```
+
+* The `Swap` struct stores data about a token exchange that has been processed successfuly. It shows both parties that participated in the swap as well as information about the associated tokens
+* The `SwapRequest` struct represents a single request for a token exchange coming from one wallet (`initiator`). It contains the token the wallet wants to exchange as well as the ID of the desired token and its amount
+* The `swaps` and `swapRequests` maps store recorded swaps and swap requests using the current counter values as keys
+
+## Contract events
+
+The contract emits the following events
+
+```solidity showLineNumbers file=../../../tests/SwapMatch.sol start=startContractEvents end=endContractEvents
+```
+
+## Placing swap requests
+
+Wallets can place new swap requests by calling this function:
+
+```solidity showLineNumbers file=../../../tests/SwapMatch.sol start=startPlaceSwapRequest end=endPlaceSwapRequest
+```
+
+The function initializes a new `SwapRequest` and increases the swap request counter. It also starts the matching process.
+
+## Matching swap requests
+
+The contract matches swap requests using this function:
+
+```solidity showLineNumbers file=../../../tests/SwapMatch.sol start=startMatchSwapRequests end=endMatchSwapRequests
+```
+
+The function iterates over all recorded swap requests and finds a suitable partner for the new swap request. This is done based on four conditions:
+
+* The 'candidate' swap request must not be matched yet
+* The 'candidate' swap request must contain at least the same amount of tokens as desired in the swap request being matched
+* The 'candidate' swap request is asking for the same token as provided in the swap request being matched
+* The swap request being matched can provide at least the same amount of tokens as desired by the 'candidate' swap request
+
+If all conditions are satisfied, the contract begins sending tokens. It also initializes a new `Swap` object and updates the relevant map and counter. 
+
+## Sending tokens and handling excesses
+
+The contract sends tokens and makes sure that both parties in a swap receive back any 'excess' tokens that could not be exchanged:
+
+```solidity showLineNumbers file=../../../tests/SwapMatch.sol start=startSendTokensAndProcessExcess end=endSendTokensAndProcessExcess
+```
+
+The function calculates the possible token excesses:
+
+* The difference between the amount of tokens desired by the matched swap request and the new swap request
+* The difference between the amount of tokens desired by the new swap request and the matched swap request
+
+The tokens are transformed into token arrays and sent to the originators of swap requests using `Nil.asyncCall()`. All refunds are also sent to these addresses. 

nil/cookbook/swap/deploy-test-swap.mdx

@@ -0,0 +1,52 @@
+# Deploy and test the swap contract
+
+This test of the `SwapMatch` contract does the follows:
+
+* Creates two new wallets 
+* Deploys the contract
+* Mints two currencies for these wallets
+* Places two swap requests (one from Wallet 1 and another from Wallet 2)
+* Evaluates whether the swap requests were matched and if excesses were returned correctly
+
+## Create two new wallets
+
+```js showLineNumbers file=../../../tests/cookbook-swap.test.mjs start=startTwoNewWalletsDeploy end=endTwoNewWalletsDeploy
+```
+
+## Deploy the contract
+
+```js showLineNumbers file=../../../tests/cookbook-swap.test.mjs start=startDeploymentOfSwapMatch end=endDeploymentOfSwapMatch
+```
+
+## Mint two new currencies
+
+```js showLineNumbers file=../../../tests/cookbook-swap.test.mjs start=startCurrencyCreation end=endCurrencyCreation
+```
+
+## Place the first swap request
+
+```js showLineNumbers file=../../../tests/cookbook-swap.test.mjs start=startFirstSendRequest end=endFirstSendRequest
+```
+
+## Place the second swap request
+
+```js showLineNumbers file=../../../tests/cookbook-swap.test.mjs start=startSecondSendRequest end=endSecondSendRequest
+```
+
+## Check the token amounts
+
+```js showLineNumbers file=../../../tests/cookbook-swap.test.mjs start=startFinalChecks end=endFinalChecks
+```
+
+Expected output:
+
+```
+Wallet 1 tokens:  {
+  TOKEN_ONE_ID: 90000000n,
+  TOKEN_TWO_ID: 20000000n
+}
+Wallet 2 tokens:  {
+  TOKEN_ONE_ID: 10000000n,
+  TOKEN_TWO_ID: 80000000n
+}
+```