Merge pull request #478 from oasisprotocol/rube/461-docs-revamp-sapph…

…ire---guide-chapter

 docs revamp: new top toolbar build

README.md

@@ -65,7 +65,7 @@ This repository includes all relevant Sapphire and dependencies organized into
 the following directories:
 
 - [`clients`](./clients): the Go, Python and JavaScript/TypeScript clients
-- [`contracts`](./contracts): Sapphire and [OPL](https://docs.oasis.io/dapp/opl/) smart contracts
+- [`contracts`](./contracts): Sapphire and [OPL](https://docs.oasis.io/build/opl/) smart contracts
 - [`docs`](./docs): topic-oriented Sapphire documentation
 - [`examples`](./examples/): sample code snippets in popular Ethereum
 development environments
@@ -76,7 +76,7 @@ development environments
 ## Documentation
 
 The Sapphire documentation is deployed as part of the official
-[Oasis documentation](https://docs.oasis.io/dapp/sapphire/). To make changes
+[Oasis documentation](https://docs.oasis.io/build/sapphire/). To make changes
 visible on the docs website:
 
 1. Merge any changes in the `docs` folder to the `main` branch.

clients/go/README.md

@@ -6,7 +6,7 @@
 style.
 
 [@oasisprotocol/sapphire-paratime]: https://pkg.go.dev/github.com/oasisprotocol/sapphire-paratime/go/
-[Sapphire ParaTime]: https://docs.oasis.io/dapp/sapphire
+[Sapphire ParaTime]: https://docs.oasis.io/build/sapphire
 
 ## Building
 
@@ -96,5 +96,5 @@ _ = c.SendTransaction(ctx, signedTx)
 ## See Also
 
 - [Oasis Testnet Faucet](https://faucet.testnet.oasis.io/)
-- [Creating dapps for Sapphire](https://docs.oasis.io/dapp/sapphire/quickstart)
+- [Creating dapps for Sapphire](https://docs.oasis.io/build/sapphire/quickstart)
 - [How to Transfer ROSE into an EVM ParaTime](https://docs.oasis.io/general/manage-tokens/how-to-transfer-rose-into-paratime/)

clients/js/README.md

@@ -11,7 +11,7 @@ The Sapphire wrapper with automatically encrypt the `eth_call`, `eth_estimateGas
 and `eth_signTransaction` JSON-RPC calls
 
 [@oasisprotocol/sapphire-paratime]: https://www.npmjs.com/package/@oasisprotocol/sapphire-paratime
-[sapphire paratime]: https://docs.oasis.io/dapp/sapphire/
+[sapphire paratime]: https://docs.oasis.io/build/sapphire/
 
 _If your dapp doesn't port in under 10 minutes, it's a bug!_<br />
 If you have more than a little trouble, please file an issue.<br />
@@ -59,5 +59,5 @@ signed queries manually using the `overrides` parameter to `SignedCallDataPack.m
 ## See Also
 
 - [Oasis Testnet Faucet](https://faucet.testnet.oasis.io/)
-- [Creating dapps for Sapphire](https://docs.oasis.io/dapp/sapphire/quickstart)
+- [Creating dapps for Sapphire](https://docs.oasis.io/build/sapphire/quickstart)
 - [How to Transfer ROSE into an EVM ParaTime](https://docs.oasis.io/general/manage-tokens/how-to-transfer-rose-into-paratime/)

contracts/README.md

@@ -34,8 +34,8 @@ contract RandomNumber {
 
 ## Documentation
 
-See the user's guide for [Sapphire](https://docs.oasis.io/dapp/sapphire/) and
-[OPL](https://docs.oasis.io/dapp/opl/).
+See the user's guide for [Sapphire](https://docs.oasis.io/build/sapphire/) and
+[OPL](https://docs.oasis.io/build/opl/).
 
 The generated API reference is hosted at
 [api.docs.oasis.io](https://api.docs.oasis.io/sol/sapphire-contracts).

docs/README.mdx

@@ -19,7 +19,8 @@ crypto gaming
 ### Getting Started
 
 Develop and deploy a dApp on Sapphire:
-- follow along with a video walkthrough via [quickstart][quickstart]
+
+- follow along with a video walkthrough via [Quickstart][quickstart]
 - start with a working dApp [demo][demo]
 - explore showcase dApps deployed on Sapphire on the [playground][playground]
 
@@ -29,20 +30,22 @@ Develop and deploy a dApp on Sapphire:
 
 ### Understanding EVM compatibility
 
-Get to know the differences between Sapphire and Ethereum, and learn about
-the high level concepts of developing a confidential smart contract with our
-[guide][guide].
+Get to know the differences between [Sapphire and Ethereum], and learn about
+the high level [Concepts] of developing dApps.
 
-[guide]: ./guide.mdx
+[Sapphire and Ethereum]: ./ethereum.mdx
+[Concepts]: ./develop/concept.mdx
 
-### Building on Sapphire
+### Develop on Sapphire
 
 Take your existing dApp building knowledge and add Sapphire with our developer
-[cheatsheet](./images/cheatsheet.pdf).
+[cheatsheet](./images/cheatsheet.pdf) or visit the [Develop on Sapphire] chapter.
+
+[Develop]: ./develop/README.mdx
 
 ### Network Information
 
-See crucial network information [here][network].
+Check out the RPC endpoints, block explorers and indexers at [Network Information][network].
 
 [network]: ./network.mdx
 
@@ -55,9 +58,8 @@ Visit the [faucet][faucet] to obtain testnet tokens for development purposes.
 ## See also
 
 <DocCardList items={[
-    findSidebarItem('/general/manage-tokens/'),
-    findSidebarItem('/node/run-your-node/paratime-node'),
-    findSidebarItem('/node/run-your-node/paratime-client-node'),
+    findSidebarItem('/build/rofl/'),
+    findSidebarItem('/build/opl/'),
     findSidebarItem('/node/web3'),
-    findSidebarItem('/dapp/tools/other-paratimes/'),
+    findSidebarItem('/build/tools/other-paratimes/'),
 ]} />

docs/develop/README.mdx

@@ -0,0 +1,116 @@
+---
+description: Develop new dApps on Sapphire
+---
+import DocCardList from '@theme/DocCardList';
+import {findSidebarItem} from '@site/src/sidebarUtils';
+
+# Develop on Sapphire
+
+As Sapphire is EVM-compatible, you can use the same dev tooling as you would
+when building on Ethereum. Additionally, we build tools to support you in
+creating secure and confidential dApps.
+
+Feel free to check out the [Concepts] page to get a better understanding of the
+transaction flow and the contract state.
+
+[Concepts]: ./concept.mdx
+
+## Contract Development
+
+Sapphire is programmable using any language that targets the EVM, such as Solidity,
+Fe or Vyper. If you prefer to use an Ethereum framework like Hardhat or Foundry,
+you can also use those with Sapphire; all you need to do is set your Web3 gateway URL.
+You can find the details of the Oasis Sapphire Web3 endpoints
+on the [Network information] page.
+
+[Network information]: ../network.mdx#rpc-endpoints
+
+### Features
+
+<DocCardList items={[
+    findSidebarItem('/build/sapphire/develop/deployment'),
+    findSidebarItem('/build/sapphire/develop/gasless'),
+    findSidebarItem('/build/sapphire/develop/security'),
+    findSidebarItem('/build/sapphire/develop/authentication'),
+]} />
+
+[Randomness, Subcalls and More Precompiles][sapphire-contracts] in the contracts API reference
+
+[sapphire-contracts]: https://api.docs.oasis.io/sol/sapphire-contracts
+
+## Frontend Development
+
+To connect your frontend to your smart contracts, see the [Browser] chapter.
+
+[Browser]: ./browser.md
+
+### More Frontend Frameworks
+
+We support the common frontend libraries with the v2 client:
+
+| Framework               | Package                                           | API Reference     | GitHub                  |
+| ----------------------- | ------------------------------------------------- | ----------------- | ----------------------- |
+| **[Ethers v6][ethers]** | [@oasisprotocol/sapphire-ethers-v6][ethers-npmjs] | [API][ethers-api] | [GitHub][ethers-github] |
+| **[Viem][viem]**        | [@oasisprotocol/sapphire-viem-v2][viem-npmjs]     | [API][viem-api]   | [GitHub][viem-github]   |
+| **[Wagmi][wagmi]**      | [@oasisprotocol/sapphire-wagmi-v2][wagmi-npmjs]   | [API][wagmi-api]  | [GitHub][wagmi-github]  |
+
+[ethers]: https://docs.ethers.org/v6/
+[ethers-npmjs]: https://www.npmjs.com/package/@oasisprotocol/sapphire-ethers-v6
+[ethers-api]: https://api.docs.oasis.io/js/sapphire-ethers-v6
+[ethers-github]: https://github.com/oasisprotocol/sapphire-paratime/tree/main/integrations/ethers-v6
+[viem]: https://viem.sh/
+[viem-npmjs]: https://www.npmjs.com/package/@oasisprotocol/sapphire-viem-v2
+[viem-api]: https://api.docs.oasis.io/js/sapphire-viem-v2
+[viem-github]: https://github.com/oasisprotocol/sapphire-paratime/tree/main/integrations/viem-v2
+[wagmi]: https://wagmi.sh/
+[wagmi-npmjs]: https://www.npmjs.com/package/@oasisprotocol/sapphire-wagmi-v2
+[wagmi-api]: https://api.docs.oasis.io/js/sapphire-wagmi-v2
+[wagmi-github]: https://github.com/oasisprotocol/sapphire-paratime/tree/main/integrations/wagmi-v2
+
+## Backend Development
+
+If you want to connect and execute transactions from your backend.
+Sapphire has three clients in different programming languages:
+
+| Language        | Package                                            | API Reference | GitHub              |
+| --------------- | -------------------------------------------------- | ------------- | ------------------- |
+| **Javascript**  | [@oasisprotocol/sapphire-paratime][sapphire-npmjs] | [API][js-api] | [GitHub][js-github] |
+| **Go**          | [@oasisprotocol/sapphire-paratime][go-pkg]         | [API][go-api] | [GitHub][go-github] |
+| **Python**      |                                                    | [API][py-api] | [GitHub][py-github] |
+
+[sapphire-npmjs]: https://www.npmjs.com/package/@oasisprotocol/sapphire-paratime
+[go-pkg]: https://pkg.go.dev/github.com/oasisprotocol/sapphire-paratime/clients/go
+[js-api]: https://api.docs.oasis.io/js/sapphire-paratime
+[go-api]: https://pkg.go.dev/github.com/oasisprotocol/sapphire-paratime/clients/go
+[py-api]: https://api.docs.oasis.io/py/sapphirepy/
+[js-github]: https://github.com/oasisprotocol/sapphire-paratime/tree/main/clients/js/README.md
+[go-github]: https://github.com/oasisprotocol/sapphire-paratime/tree/main/clients/go/README.md
+[Py-github]: https://github.com/oasisprotocol/sapphire-paratime/tree/main/clients/py/README.md
+
+## Testing 
+
+[Test][testing] confidential contracts with Hardhat or Ethers.
+
+[testing]: ./testing.md
+
+## Examples
+
+See our [Examples] page for demo dApps that bring all the above together.
+
+[examples]: ../examples.mdx
+
+## Tools and Services
+
+<DocCardList items={[
+    findSidebarItem('/build/tools/abi-playground'),
+    findSidebarItem('/build/tools/localnet'),
+    findSidebarItem('/build/tools/remix'),
+    findSidebarItem('/build/tools/verification'),
+    findSidebarItem('/build/tools/band'),
+]} />
+
+Should you have any questions or ideas to share, feel free to reach out to us
+on [discord and other social media channels][social-media].
+
+[social-media]: https://github.com/oasisprotocol/docs/blob/main/docs/get-involved/README.md#social-media-channels
+

docs/authentication.md → docs/develop/authentication.md

@@ -74,7 +74,7 @@ which created the contract, calling `isOwner` will return:
  * `false`, with `sapphire.wrap` but without an attached signer
  * `true`, with `sapphire.wrap` and an attached signer
  * `true`, if called via the contract which created it
-* `true`, if called via transaction
+ * `true`, if called via transaction
 
 ## Caching Signed Queries
 

docs/browser.md → docs/develop/browser.md

@@ -44,12 +44,11 @@ access them!**
 
 The contract in the Hardhat boilerplate is ERC-20-compatible and emits the
 `transfer` event. If your wish to preserve confidentiality, you can comment
-out [line 66]. Read [the guide](guide.mdx#contract-logs) to learn more.
+out [line 66]. Read the [concept] chapter to learn more.
 
 :::
 
-[`wagmi`]: https://wagmi.sh/
-[`viem`]: https://viem.sh/
+[concept]: ./concept.mdx#contract-logs
 
 ## Signing Sapphire Calls and Transactions in Browser
 
@@ -155,21 +154,21 @@ npm run start
 If all goes well the web server will spin up and your browser should
 automatically open `http://localhost:3000`.
 
-![Hardhat boilerplate frontend](images/hardhat-boilerplate-frontend1.png)
+![Hardhat boilerplate frontend](../images/hardhat-boilerplate-frontend1.png)
 
 Go ahead and connect the wallet. If you haven't done it yet, you will have
 to add the [Sapphire ParaTime Testnet network to your
 Metamask][sapphire-testnet]. Once connected, the frontend will make an unsigned
 call to the `balanceOf` view and show you the amount of `MHT`s in your selected
 Metamask account.
 
-![MHT balance of your account](images/hardhat-boilerplate-frontend2.png)
+![MHT balance of your account](../images/hardhat-boilerplate-frontend2.png)
 
 Next, let's transfer some `MHT`s. Fill in the amount, the address and hit the
 *Transfer* button. Metamask will show you the popup to sign and submit the
 transfer transaction. Once confirmed, Metamask will both **sign and encrypt** the transaction.
 
-![Sign and encrypt the transfer transaction](images/hardhat-boilerplate-frontend3.png)
+![Sign and encrypt the transfer transaction](../images/hardhat-boilerplate-frontend3.png)
 
 Once the transaction is processed, you will get a notification from Metamask
 and the balance in the dApp will be updated.
@@ -207,14 +206,13 @@ we recommend that you check out the official [Oasis starter] files.
 :::
 
 [block explorer]: https://explorer.oasis.io/testnet/sapphire/tx/0x3303dea5d48291d1564cad573f21fc71fcbdc2b862e17e056287fd9207e3bc53
-[guide-transaction-calls]: guide.mdx#transactions--calls
+[guide-transaction-calls]: ./concept.mdx#transactions--calls
 [Hardhat boilerplate repo]: https://github.com/NomicFoundation/hardhat-boilerplate
 [Hardhat boilerplate]: https://hardhat.org/tutorial/boilerplate-project
-[Hardhat tutorial]: https://hardhat.org/tutorial
 [line 66]: https://github.com/NomicFoundation/hardhat-boilerplate/blob/13bd712c1285b2de572f14d20e6a750ae08565c0/contracts/Token.sol#L66
-[quickstart]: quickstart.mdx#add-the-sapphire-testnet-to-hardhat
-[sapphire-testnet]: ./network.mdx#rpc-endpoints
+[quickstart]: ../quickstart.mdx#add-the-sapphire-testnet-to-hardhat
+[sapphire-testnet]: ../network.mdx#rpc-endpoints
 [Sapphire ParaTime examples]: https://github.com/oasisprotocol/sapphire-paratime/tree/main/examples/hardhat-boilerplate
 [social-media]: https://github.com/oasisprotocol/docs/blob/main/docs/get-involved/README.md#social-media-channels
 [pnpm]: https://pnpm.io
-[TEST tokens]: quickstart.mdx#get-some-sapphire-testnet-tokens
+[TEST tokens]: ../quickstart.mdx#get-some-sapphire-testnet-tokens