flashbots · andytudhope · Oct 6, 2023 · Oct 4, 2023 · Oct 4, 2023 · Oct 4, 2023
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "docs/technical"]
+	path = docs/technical
+	url = [email protected]:flashbots/suave-specs.git
diff --git a/...al-details/precompiles/write-your-own.mdx → docs/how-to/add-a-precompile.mdx b/...al-details/precompiles/write-your-own.mdx → docs/how-to/add-a-precompile.mdx
@@ -37,7 +37,7 @@ functions:
   - name: confidentialInputs
     address: "0x0000000000000000000000000000000042010001"
     output:
-      packed: true
+      plain: true
       fields:
         - name: output1
           type: bytes
@@ -68,7 +68,7 @@ The fields you can include when adding a new `function` to the `yaml` specificat
     - `name`: Name of the input field
     - `type`: Type of the input field.
 - `output`: Configuration of the expected output.
-    - `packed`: Boolean that specifies whether to pack the output. Only available if the function returns a single array of bytes.
+    - `plain`: Boolean that specifies whether to pack the output. Only available if the function returns a single array of bytes.
     - `fields`: Array of output fields for the precompile.
         - `name`: Name of the output field
         - `type`: Type of the output field.
@@ -123,4 +123,6 @@ You will now need to write the logic required for your precompile to work as exp
 func (b *suaveRuntime) Add(a uint64, b uint64) (uint64, error) {
     return a+b, nil
 }
-````
+````
+
+You can find a workd example of how to add a more complicated precompile in [this PR](https://github.com/flashbots/suave-geth/pull/66/files).
diff --git a/docs/how-to/index.mdx b/docs/how-to/index.mdx
@@ -12,7 +12,7 @@ SUAVE is focused on delivering credible, confidential computation that enables y
 ## What can I do with SUAVE?
 
 1. **Deploy more expressive smart contracts.** 
-    - Contracts on SUAVE follow the same rules as on Ethereum, with the added advantage of being able to access additional precompiles available to serve any MEV application. We call this [builder solidity](/technical-details/builder-solidity).
+    - Contracts on SUAVE follow the same rules as on Ethereum, with the added advantage of being able to access additional precompiles available to serve any MEV application. We call this [builder solidity](/key-concepts/builder-solidity).
 
 2. **Compute confidentially**. 
     - Builder solidity lets you request confidential computation, where your transaction data is encrypted to specific actors. Public contracts with verifiable logic, combined with confidential data, means that SUAVE can be seen as an open marketplace for mechanisms we can all inspect, collaborate on, and compete with to produce the most efficient MEV applications, while nevertheless protecting everyone's privacy.

diff --git a/docs/how-to/run-suave.mdx b/docs/how-to/run-suave.mdx
@@ -68,10 +68,10 @@ Step 3: Send backrun
 
 Both the MEVM instance and the Chain instance are now running in separate containers, which means your local SUAVE dev environment is ready to go. If you followed through with Step 4 above, you've also deployed a contract in your local environment and sent some transactions to it.
 
-1. Learn more about the contract you deployed and what those transactions are in our [worked examples](/technical-details/builder-solidity/worked-examples/mev-share).
-2. Read more about [confidential computation](/technical-details/confidential-computation/) and the [APIs we've built to enable it](/technical-details/confidential-computation/apis).
-3. Dig deeper in the [architecture of the MEVM](/technical-details/MEVM#architecture).
-4. Browse a full list of the [precompiles](/technical-details/precompiles) this gives you access to in [builder solidity](/technical-details/builder-solidity/).
+1. Learn more about the contract you deployed and what those transactions are in our [how to write builder solidity guide](/how-to/write-builder-solidity).
+2. Read more about [confidential computation](/key-concepts/confidential-computation/).
+3. Dig deeper in the [architecture of the MEVM](/technical/specs/rigil/mevm) and the [APIs available](/technical/specs/rigil/mevm#confidential-apis).
+4. Browse a full list of [SUAVE precompiles](/technical/specs/rigil/precompiles).
 5. If you'd like to examine the Go code responsible for deploying contracts and sending transactions, you can do so [here](https://github.com/flashbots/suave-geth/blob/main/suave/devenv/cmd/main.go).
 
 ### Common problems

diff --git a/...er-solidity/worked-examples/mev-share.mdx → docs/how-to/write-builder-solidity.mdx b/...er-solidity/worked-examples/mev-share.mdx → docs/how-to/write-builder-solidity.mdx
diff --git a/docs/index.mdx b/docs/index.mdx
@@ -46,7 +46,7 @@ This site encourages you to move through a specific flow in order to start build
 
 1. Begin with **[tutorials](/)**. These are _learning-oriented_. They focus on practical skills, not theoretical knowledge. Our goal with the tutorials is that you enjoy the experience and gain confidence, not that you become an expert.
 2. Grow with the **[how to guides](/how-to/)**. These are _task-oriented_. You can think of them like recipes. Following a recipe requires basic competence. Recipes do not give you context or history: they will help you do stuff. All the recipes taken together help frame a general picture of how SUAVE enables you.
-3. Consult the **[technical details](/technical-details/)**. These are _information-oriented_ and provide you with up-to-date certainty about what interfaces and precompiles SUAVE provides and where to find them. These are our treasure maps, which tell you what you need to know about the territory you're working in, without having to go and constantly check yourself.
+3. Consult the **[technical specs](/technical/)**. These are _information-oriented_ and provide you with up-to-date certainty about what interfaces and precompiles SUAVE provides and where to find them. These are our treasure maps, which tell you what you need to know about the territory you're working in, without having to go and constantly check yourself.
 4. Refine your **[understanding of MEV](/understand/)**. This section is _discussion-oriented_. It does not present "the right way", but rather encourages you to reflect on "the deep why", ideally in dialogue with friends. Why does it matter that we work on MEV?
 
 <AlignItems horizontal="center" vertical="center" sideMargin={0}>
@@ -56,7 +56,7 @@ This site encourages you to move through a specific flow in order to start build
     <area shape="rect" coords="50,50,250,250" href="/" alt="Tutorials" />
     <area shape="rect" coords="330,0,550,250" href="/how-to" alt="How To Guides" />
     <area shape="rect" coords="20,300,250,600" href="/understand" alt="Understanding MEV" />
-    <area shape="rect" coords="330,300,550,600" href="/technical-details" alt="Technical Details" />
+    <area shape="rect" coords="330,300,550,600" href="/technical" alt="Technical Specs" />
   </map>
 </div>
 </AlignItems>

diff --git a/...hnical-details/builder-solidity/index.mdx → docs/key-concepts/builder-solidity.mdx b/...hnical-details/builder-solidity/index.mdx → docs/key-concepts/builder-solidity.mdx
@@ -43,10 +43,10 @@ This enables us to combine the collective verifiability we expect from blockchai
 
 ## Worked examples
 
-To dive deeper into how builder solidity actually works, we recommend that you begin with our **[MEV-Share worked example](/technical-details/builder-solidity/worked-examples/mev-share)**.
+To dive deeper into how builder solidity actually works, we recommend that you begin with our [how to write builder solidity guide](/how-to/write-builder-solidity).
 
 ## Further context
 
 We recommend [this early research talk from Andrew Miller](https://youtu.be/DhsDFKnHPa0?t=344) to get a sense of the ideas from which builder solidity has grown.
 
-Please note that the pseudo code Andrew shows is now outdated and you are better off learning from our [MEV-Share worked example](/technical-details/builder-solidity/worked-examples/mev-share) above, or looking directly at our [list of available precompiles](/technical-details/precompiles). That said, the framework used in this talk and the background provided should still prove useful when writing your own builder solidity contracts.
+Please note that the pseudo code Andrew shows is now outdated and you are better off learning from our [how to write builder solidity guide](/how-to/write-builder-solidity) above, or looking directly at our [list of available precompiles](/technical/specs/rigil/precompiles). That said, the framework used in this talk and the background provided should still prove useful when writing your own builder solidity contracts.
diff --git a/...etails/confidential-computation/index.mdx → ...key-concepts/confidential-computation.mdx b/...etails/confidential-computation/index.mdx → ...key-concepts/confidential-computation.mdx
@@ -15,7 +15,7 @@ import AlignItems from "@site/src/components/AlignItems/AlignItems.tsx"
 
 SUAVE nodes have two modes of operation: regular and confidential (sometimes called off-chain). 
 
-Regular mode is the same as the normal EVM. Confidential mode uses [the MEVM](/technical-details/MEVM), with its [additional APIs](/technical-details/confidential-computation/apis), and the [precompiles](/technical-details/precompiles) available in [builder solidity](/technical-details/builder-solidity/index), to ensure that transaction data provided by users remains private until executed on their blockchain of choice.
+Regular mode is the same as the normal EVM. Confidential mode uses [the MEVM](/technical/specs/rigil/mevm), with its [additional APIs](/technical/specs/rigil/mevm#confidential-apis), and the [precompiles](/technical/specs/rigil/precompiles) available in [builder solidity](/key-concepts/builder-solidity), to ensure that transaction data provided by users remains private until executed on their blockchain of choice.
 
 Builder solidity uses (and extends) all the tools and patterns you know and love. However, the concept of confidential computation being done off-chain by specific SUAVE nodes is new and worth emphasizing. 
 
@@ -40,7 +40,7 @@ We describe here what occurs when you want your transaction data to _remain conf
 3. The `confidentialComputeResult` is set as the calldata in a "SUAVE transaction", which is broadcast to the public mempool.
 4. We call this a "SUAVE transaction" because it is a normal EVM transaction, with an extra check to make sure that the SUAVE node's signature matches the requested SUAVE node in (1)
 
-Please take a look through our detailed [worked examples](/technical-details/builder-solidity/worked-examples/mev-share) page if you want to dive deeper into the specifics of how each step occurs.
+Please take a look through our [how to write builder solidity guide](/how-to/write-builder-solidity) if you want to dive deeper into the specifics of how each step occurs.
 
 ## Key terms
 
@@ -74,7 +74,7 @@ For clarity, let's define `confidentialComputeRequest` and `confidentialComputeR
 3. `confidentialDataStore` is an offchain data store. Builder solidity contracts tell the MEVM where to store particular information, such that the MEVM can access information other functions (or other contracts) need without storing it in the contract on chain and thereby exposing it to everyone.
     1. Builder solidity contracts tell the MEVM to store data relevant to its operation in specific "keyspaces". 
     2. This is done locally, on the specific SUAVE node for whom the `confidentialComputeRequest` was encrypted.
-    2. It's best to look directly at our [worked examples](/technical-details/builder-solidity/worked-examples/mev-share#1-the-trade) to get a deeper intutition for how this happens and why it's necessary.
+    2. It's best to look directly at our [how to write builder solidity guide](/how-to/write-builder-solidity) to get a deeper intutition for how this happens.
 
 ## Pictures
 
@@ -108,7 +108,7 @@ For clarity, let's define `confidentialComputeRequest` and `confidentialComputeR
   <summary>3. How do confidential transactions result in stuff happening (like blocks being built) on other blockchains?</summary>
   <div>
     <div>
-      What we describe above occurs on SUAVE. It is the responsibility of applications on SUAVE to broadcast blocks that have been built, or the result of various kinds of auction, back to other blockchains (like Ethereum). At first, we assume that this will happen via already-established relays. You can see a <a href="/technical-details/builder-solidity/worked-examples/mev-share#3-the-build">worked example involving block building here</a>.
+      What we describe above occurs on SUAVE. It is the responsibility of applications on SUAVE to broadcast blocks that have been built, or the result of various kinds of auction, back to other blockchains (like Ethereum). At first, we assume that this will happen via already-established relays. You can see a <a href="/how-to/write-builder-solidity#3-the-build">worked example involving block building here</a>.
     </div>
   </div>
 </details>
diff --git a/docs/key-concepts/index.mdx b/docs/key-concepts/index.mdx
diff --git a/docs/technical-details/precompiles/index.mdx → docs/key-concepts/precompiles.mdx b/docs/technical-details/precompiles/index.mdx → docs/key-concepts/precompiles.mdx
@@ -59,7 +59,7 @@ contract FetchAndEmit {
 }
 ```
 
-Please check our [worked examples pages](/technical-details/builder-solidity/worked-examples/mev-share) for further ideas about how to leverage all the precompiles available.
+Please check our [how to write builder solidity guide](/how-to/write-builder-solidity) for more ideas about how to leverage all the precompiles available.
 
 Once you are familiar with what is currently on offer, we invite you to [look at the implementation](https://github.com/flashbots/suave-geth/blob/main/core/vm/contracts_suave.go) and help us extend what is available.
 

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -15,40 +15,32 @@ module.exports = {
       collapsed: false,
       link: {type: 'doc', id: 'how-to/index'},
       items: [
-        'how-to/run-suave',
+        'how-to/run-suave', 'how-to/write-builder-solidity', 'how-to/add-a-precompile'
       ],
     },
     {
       type: 'category',
-      label: '🤖 Technical Details',
+      label: '🗝️ Key Concepts',
       collapsed: false,
-      link: {type: 'doc', id: 'technical-details/index'},
+      link: {type: 'doc', id: 'key-concepts/index'},
+      items: [
+        'key-concepts/builder-solidity', 'key-concepts/precompiles', 'key-concepts/confidential-computation',
+      ],
+    },
+    {
+      type: 'category',
+      label: '🤖 Technical Specs',
+      collapsed: false,
+      link: {type: 'doc', id: 'technical/README'},
       items: [
         {
           type: 'category',
-          label: 'Builder Solidity',
-          link: {type: 'doc', id: 'technical-details/builder-solidity/index'},
-          items: [
-            'technical-details/builder-solidity/worked-examples/mev-share',
-          ],
-        },
-        {
-          type: 'category',
-          label: 'Confidentiality',
-          link: {type: 'doc', id: 'technical-details/confidential-computation/index'},
-          items: [
-            'technical-details/confidential-computation/apis',
-          ],
-        },
-        {
-          type: 'category',
-          label: 'Precompiles',
-          link: {type: 'doc', id: 'technical-details/precompiles/index'},
+          label: 'Rigil',
+          link: {type: 'doc', id: 'technical/specs/rigil/README'},
           items: [
-            'technical-details/precompiles/write-your-own',
+            'technical/specs/rigil/suave-chain', 'technical/specs/rigil/computor', 'technical/specs/rigil/mevm', 'technical/specs/rigil/confidential-data-store', 'technical/specs/rigil/bridge', 'technical/specs/rigil/precompiles',
           ],
         },
-        'technical-details/MEVM',
       ],
     },
     {

diff --git a/docs/technical b/docs/technical
-Original file line number
+Diff line change
@@ Expand Up / @@ -59,7 +59,7 @@ contract FetchAndEmit { @@
     }
     ```
-    Please check our [worked examples pages](/technical-details/builder-solidity/worked-examples/mev-share) for further ideas about how to leverage all the precompiles available.
+    Please check our [how to write builder solidity guide](/how-to/write-builder-solidity) for more ideas about how to leverage all the precompiles available.
     Once you are familiar with what is currently on offer, we invite you to [look at the implementation](https://github.com/flashbots/suave-geth/blob/main/core/vm/contracts_suave.go) and help us extend what is available.
@@ Expand Down @@