docs revamp: new top toolbar build #478
+533
−329
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| --- | ||
| description: Develop new dApps on Sapphire | ||
| --- | ||
|
|
||
| # Develop | ||
|
|
||
| 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 [Concept] page to get a better understanding of the | ||
| transaction flow and the contract state. | ||
|
|
||
| [Concept]: ./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 | ||
|
|
||
| - [Deployment and Proxies][deployment] | ||
| - [Gasless and Onchain Signing][gasless] | ||
| - [Security considerations][security] | ||
| - [View-call authentication][view-call] | ||
| - [Randomness, Subcalls and More Precompiles][sapphire-contracts] | ||
|
Comment on lines
+28
to
+32
There was a problem hiding this comment. Let's match these titles with the actual ones in the nav bar. I would actually use the doccards here. |
||
|
|
||
| [deployment]: ./deployment.md | ||
| [gasless]: ./gasless.md | ||
| [security]: ./security.md | ||
| [view-call]: ./authentication.md | ||
| [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 | ||
|
|
||
| ## Examples | ||
|
|
||
| See our [Examples] page for demo dApps that bring all the above together. | ||
|
|
||
| [examples]: ../examples.mdx | ||
|
|
||
| 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 | ||
|
|
||
|
There was a problem hiding this comment. Something tells me we should mention other Sapphire-related tools here: ABI playground, Contract Verification, BAND, Localnet, Remix and Faucet. Perhaps add |
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| --- | ||
| description: Sapphire concepts | ||
| --- | ||
|
|
||
| import DocCard from '@theme/DocCard'; | ||
| import {findSidebarItem} from '@site/src/sidebarUtils'; | ||
|
|
||
| # Concepts | ||
|
|
||
| ## Transactions & Calls | ||
|
|
||
| {/*-- https://github.com/oasisprotocol/docs/blob/455980674563cad92ff1e1b62a7a5f2d4d6809f0/docs/general/images/architecture/client-km-compute.svg -->*/} | ||
|  | ||
|
|
||
| The figure above illustrates the flow of a **confidential smart contract | ||
| transaction** on Sapphire. | ||
|
|
||
| Transactions and calls must be encrypted and signed for maximum security. | ||
| The [@oasisprotocol/sapphire-paratime] npm package will make your life | ||
| easy. It'll handle cryptography and signing for you. | ||
|
|
||
| You should be aware that taking actions based on the value of private data may | ||
| **leak the private data through side channels** like time spent, gas use and | ||
| accessed memory locations. If you need to branch on private data, you should in | ||
| most cases ensure that both branches exhibit the same time/gas and storage | ||
| patterns. | ||
|
|
||
| You can also make **confidential smart contract calls** on Sapphire. If you | ||
| use `msg.sender` for access control in your contract, the call **must be | ||
| signed**, otherwise `msg.sender` will be zeroed. On the other hand, set the | ||
| `from` address to all zeros, if you want to avoid annoying signature popups in | ||
| the user's wallet for calls that do not need to be signed. The JS library will | ||
| do this for you. | ||
|
|
||
| :::note | ||
|
|
||
| Inside the smart contract code, there is no way of knowing whether the | ||
| client's call data were originally encrypted or not. | ||
|
|
||
| ::: | ||
|
|
||
| <details> | ||
| <summary>Detailed confidential smart contract transaction flow on Sapphire</summary> | ||
|
|
||
|  | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Detailed confidential smart contract call flow on Sapphire</summary> | ||
|
|
||
|  | ||
|
|
||
| </details> | ||
|
|
||
| ## Contract State | ||
|
|
||
| The Sapphire state model is like Ethereum's except for all state being encrypted | ||
| and not accessible to anyone except the contract. The contract, executing in an | ||
| active (attested) Oasis compute node is the only entity that can request its | ||
| state encryption key from the Oasis key manager. Both the keys and values of the | ||
| items stored in state are encrypted, but the **size of either is not hidden**. Your | ||
| app may need to pad state items to a constant length, or use other obfuscation. | ||
| Observers may also be able to infer computation based on storage access patterns, | ||
| so you may need to obfuscate that, too. See [Security chapter] for more | ||
| recommendations. | ||
|
|
||
| [Security chapter]: ./security.md#storage-access-patterns | ||
|
|
||
| :::danger Contract state leaks a fine-grained access pattern | ||
|
|
||
| Contract state is backed by an encrypted key-value store. However, the trace of | ||
| encrypted records is leaked to the compute node. As a concrete example, an ERC-20 | ||
| token transfer would leak which encrypted record is for the sender's account | ||
| balance and which is for the receiver's account balance. Such a token would be | ||
| traceable from sender address to receiver address. Obfuscating the storage access | ||
| patterns may be done by using an ORAM implementation. | ||
|
|
||
| ::: | ||
|
|
||
| Contract state may be made available to third parties through logs/events, or | ||
| explicit getters. | ||
|
|
||
| ## Contract Logs | ||
|
|
||
| Contract logs/events (e.g., those emitted by the Solidity `emit` keyword) | ||
| are exactly like Ethereum. Data contained in events is *not* encrypted. | ||
| Precompiled contracts are available to help you encrypt data that you can | ||
| then pack into an event, however. | ||
|
|
||
| :::danger Unmodified contracts may leak state through logs | ||
|
|
||
| Base contracts like those provided by OpenZeppelin often emit logs containing | ||
| private information. If you don't know they're doing that, you might undermine | ||
| the confidentiality of your state. As a concrete example, the ERC-20 spec | ||
| requires implementers to emit an `event Transfer(from, to, amount)`, which is | ||
| obviously problematic if you're writing a confidential token. What you can | ||
| do instead is fork that contract and remove the offending emissions. | ||
|
|
||
| ::: | ||
rube-de marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## See also | ||
|
|
||
| <DocCard item={findSidebarItem('/build/sapphire/ethereum')} /> | ||
File renamed without changes.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.