feat: update docs (#52)

* feat: update docs (wip) * fix image link * add explore section * update badges.md * update * update README * nit * add section about upgradability * improve docs and add examples * add license * fix code formatting
scroll-tech · Aug 29, 2024 · 38ce0dc · 38ce0dc
1 parent c08e809
commit 38ce0dc
Show file tree

Hide file tree

Showing 8 changed files with 747 additions and 74 deletions.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Scroll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -2,63 +2,88 @@
 
 [![test](https://github.com/scroll-tech/canvas-contracts/actions/workflows/contracts.yml/badge.svg)](https://github.com/scroll-tech/canvas-contracts/actions/workflows/contracts.yml)
 
-![Components overview](images/overview.png "Overview")
+## Welcome to Scroll Canvas
 
-([Editable link](https://viewer.diagrams.net/?tags=%7B%7D&highlight=0000ff&edit=_blank&layers=1&nav=1&title=skelly-v4.drawio#R7VpLc6M4EP41rpo5xIWEMeYYx8nsIdma2Rx2clRABs0K5BVybO%2BvXwkknk7ijCEwNalUyqjVenV%2F%2FVDDxL6K91842kR3LMB0Aq1gP7FXEwgBsIH8UZRDTllY85wQchJoppJwT%2F7Dmmhp6pYEOK0xCsaoIJs60WdJgn1RoyHO2a7Otma0vuoGhbhFuPcRbVP%2FJoGI9Ckcq6T%2FgUkYmZWBpXtiZJg1IY1QwHYVkn09sa84YyJ%2FivdXmCrhGbnk426e6S02xnEiThkQf%2Ft2uwvggibu7Q9%2Fk1hfCbzQykjFwRwYB%2FL8usm4iFjIEkSvS%2BqSs20SYDWrJVslzy1jG0kEkvgDC3HQykRbwSQpEjHVvXLD%2FPBdj88aD6oxdUxzta92rg66lQrO%2FinUIAW4XBNKrxhlPNu7vV742PcLzkrP48KZOWqOttS0IFO25T5%2BQVQGfYiHWLzAZ%2Bd8So6VBbROvmAWY3kmycAxRYI81XGGNFzDgq%2FUqHzQSn2DgsEsn%2FgJ0a1eagLnVB5gGZCnmurn%2F24VFpd%2BLrZLtcfw8ZPjTaBc2yp%2FP2dylLaUiIs1igk95Nx3OKEsZ7qTgPD1s5wZxRIZSz3%2FlZQ0wVz2%2FIl3zc58SMwSlm6Q0kexUprBSa0DrM0%2B76AkwReRtr%2Bsy9Fd82K%2Beah%2BkRA4FZ8%2Bm8NLYWbnz3uPWsEtepTOrIZcREmYyGdfokeewF4%2BYS6I9BaXuiMmQZAbCZb7RY%2FZfAp3G0YSkSnXWU6clcKuPJQxNKsNy5fMVa2K95Mj%2Fk%2BvWHMxNdTpURfW1Fo4bj72UJvpZFzqyb%2Bqk5WzXHj1EWy9TqW9NHFcbOkMaLeQfX1539LkLiIC3%2BdYWu1kkGpoNN3kYWNN9sqn1dRyxMeCZzTwrKTthVWTsu3q9q4STjQpqkQSQ%2BvcI8CW2O79CMfIWMYjN1bxFw5JapY8R6Ytd7zM%2FrS0j9F7EDx0Bha8O2isLRqnxVq8J%2BJ7ySlbD5WecpBq1OPzm9T5atS1T4y6cFRR12uperCkqR5mOrXFzpQ3G5XyzNVjDNobNuU9VX%2FOqPRnHwlwnFG6RGp%2FR6JcyuiTykdHljk4zsgyh%2FZVoibYDsXXsaM6XeZuU%2BZwYJk77ybzLiDbFN9saPEB%2BJv48ld9NOjaRzeufxoB0G0gADRUmwcdPaqHS2Hb%2B3%2FUO37Zeocx304KHrAGTN06E%2B5FsmiqH4v6DD1WPxYfQFe%2F1pRnZQrMxwT202Ppm5Hs2I26Rn%2BVonbForfgCU8tSIBqOaIoTrxfQQLOhwq4512KwFEz6L36FFyql3CymbAE55QborauFYS4MBw%2BRWlKfEPWbKBnPfadEIFZw1y9hrnmQGolRFIq6FBh0z7mzevc%2FBy%2FfMh30GnQMkKvBK3LLFFRUaN5Mf%2FK2f782vMorpWwKeyha9HwI3vIMEbSdIuzu%2FSYsodXUuXOUom5Z00tS6JzMfechV2%2FuM1U38yZyX%2FHdW3YV2CyPpBYXtiWh7YfXGGKQxmCWDImjPYIS5DBEngAQMe1JDgXdec596ae58zmnu1CD3p9AXPgb2PKetJDte%2B59PiVTCtAaZTtC5yVNRk38Ktlv27LyUh7Q340Dst5EX%2Fn25M1BZb51uNns9n%2BCxoGWhUdyQxwTej4ytzNTwtm3sDpnH3sK68hndfkTZXxM%2FzRqa8oDbpedUhlvdC27XpKZGp9I7ah9usin2Mk2iY0Ij9nsNtFjRdA68zCrinkNt9b9Ki09iuLwvH19klW1y4RgndzibJZfjWdK6H89ty%2B%2Fh8%3D))
+We are thrilled to have you join us in building unique discoveries with [Scroll Canvas](https://scroll.io/canvas), a new product designed for ecosystem projects to interact with users in a more tailored way.
 
-## ScrollBadge Schema and Resolver
+Try Canvas at [scroll.io/canvas](https://scroll.io/canvas)
 
-We define a *Scroll badge* [EAS schema](https://docs.attest.sh/docs/core--concepts/schemas):
+## Overview
 
-```
-address badge
-bytes   payload
+**Scroll Canvas** allows users to showcase on-chain credentials, status, and achievements called **Badges** issued and collected across the Scroll ecosystem.
+Users can mint a non-transferable and unique personal persona to collect and display their **Badges**.
+
+### Key Features
+
+- **Canvas**: Each Canvas is a smart contract minted through the `ProfileRegistry` contract by the user on Scroll’s website.
+- **Badges**: Attestations of achievements and traits verified through the [Ethereum Attestation Service](https://docs.attest.sh/docs/welcome) (EAS), issued by different projects and the Scroll Foundation.
+  Badges are wallet-bound and non-transferable.
+
+Differences between attestations and NFTs:
+
+| Attestation | NFT |
+| --- | --- |
+| Witness Proofs | Tokenized Assets |
+| Non-transferable | Transferable |
+| Recorded on disk (blockchain history) | Recorded in memory (blockchain states) |
+| Prove ownership at a point in time | Exercise custodianship of an asset |
+
+## Developer Quickstart
+
+Visit the [Developer Documentation](./docs) in this repo to learn more about Canvas.
+
+See [Deployments](./docs/deployments.md) for the official Canvas contract addresses.
+
+See the [Integration Guide](https://scrollzkp.notion.site/Introducing-Scroll-Canvas-Badge-Integration-Guide-8656463ab63b42e8baf924763ed8c9d5) for more information.
+
+## Support
+
+For questions regarding Canvas and custom badge development, please join [Scroll dev support channel](https://discord.com/channels/853955156100907018/1028102371894624337) on Discord.
+
+## Running the Code
+
+### Node.js
+
+First install [`Node.js`](https://nodejs.org/en) and [`npm`](https://www.npmjs.com/).
+Run the following command to install [`yarn`](https://classic.yarnpkg.com/en/):
+
+```bash
+npm install --global yarn
 ```
 
-This schema is tied to `ScrollBadgeResolver`.
-Every time a Scroll badge attestation is created or revoked, `ScrollBadgeResolver` executes some checks.
-After that, it forwards the call to the actual badge implementation.
+### Foundry
 
-## Profiles
+Install `foundryup`, the Foundry toolchain installer:
 
-Each user can create a `Profile` contract, minted through the `ProfileRegistry` contract.
-Each wallet can mint only one profile.
-All profiles share the same implementation, upgradable by Scroll to enable new features.
+```bash
+curl -L https://foundry.paradigm.xyz | bash
+```
 
-The main use of profiles is personalization.
-Users can configure a username and an avatar.
-Users can also decide which badges they atach to their profile, and in which order.
+If you do not want to use the redirect, feel free to manually download the `foundryup` installation script from [here](https://raw.githubusercontent.com/foundry-rs/foundry/master/foundryup/foundryup). Then, run `foundryup` in a new terminal session or after reloading `PATH`.
 
-## Badges
+Other ways to install Foundry can be found [here](https://github.com/foundry-rs/foundry#installation).
 
-Each badge is an EAS attestation that goes through the `ScrollBadgeResolver` contract and a badge contract.
+### Install Dependencies
 
-Each badge type is a standalone contract, inheriting from `ScrollBadge`.
-This badge contract can implement arbitrary logic attached to the attestation.
-Badges implement a `badgeTokenURI` interface, similar to `ERC721.tokenURI`.
+Run the following command to install all dependencies locally.
 
-Badges are minted to the user's wallet address.
-The user can express their personalization preferences (attach and order badges, choose a profile photo) through their `Profile`.
+```
+yarn
+```
+
+### Run Contract Tests
+
+Run the following command to run the contract tests.
 
-See [badges](./docs/badges.md) for details.
+```
+yarn test
+```
 
-### Extensions
+## Contributing
 
-This repo contains some useful [extensions](src/badge/extensions):
-- `ScrollBadgeAccessControl` restricts who can create and revoke this badge.
-- `ScrollBadgeCustomPayload` adds custom payload support to the badge.
-- `ScrollBadgeDefaultURI` sets a default badge token URI.
-- `ScrollBadgeEligibilityCheck` adds a standard on-chain eligibility check interface.
-- `ScrollBadgeNoExpiry` disables expiration for the badge.
-- `ScrollBadgeNonRevocable` disables revocation for the badge.
-- `ScrollBadgeSBT` attaches an SBT token to each badge attestation.
-- `ScrollBadgeSelfAttest` ensures that only the recipient of the badge can create the badge.
-- `ScrollBadgeSingleton` ensures that each user can only have at most one of the badge.
+We welcome community contributions to this repository.
+For larger changes, please [open an issue](https://github.com/scroll-tech/canvas-contracts/issues/new/choose) and discuss with the team before submitting code changes.
 
-### Examples
+## License
 
-This repo also contains some [examples](src/badge/examples):
-- `ScrollBadgeSimple` is a simple badge with fixed metadata.
-- `ScrollBadgePermissionless` is a permissionless badge that anyone can mint to themselves.
-- `ScrollBadgeLevels` is an SBT badge that stores a level in its payload and renders different images based on this level.
-- `ScrollBadgeTokenOwner` is a badge that is tied to the ownership of a Scroll Origins NFT.
+Scroll Monorepo is licensed under the [MIT](./LICENSE) license.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,70 @@
+# Scroll Canvas Developer Documentation
+
+![Components overview](../images/overview.png "Overview")
+
+([Editable link](https://viewer.diagrams.net/?tags=%7B%7D&highlight=0000ff&edit=_blank&layers=1&nav=1&title=skelly-v4.drawio#R7VpLc6M4EP41rpo5xIWEMeYYx8nsIdma2Rx2clRABs0K5BVybO%2BvXwkknk7ijCEwNalUyqjVenV%2F%2FVDDxL6K91842kR3LMB0Aq1gP7FXEwgBsIH8UZRDTllY85wQchJoppJwT%2F7Dmmhp6pYEOK0xCsaoIJs60WdJgn1RoyHO2a7Otma0vuoGhbhFuPcRbVP%2FJoGI9Ckcq6T%2FgUkYmZWBpXtiZJg1IY1QwHYVkn09sa84YyJ%2FivdXmCrhGbnk426e6S02xnEiThkQf%2Ft2uwvggibu7Q9%2Fk1hfCbzQykjFwRwYB%2FL8usm4iFjIEkSvS%2BqSs20SYDWrJVslzy1jG0kEkvgDC3HQykRbwSQpEjHVvXLD%2FPBdj88aD6oxdUxzta92rg66lQrO%2FinUIAW4XBNKrxhlPNu7vV742PcLzkrP48KZOWqOttS0IFO25T5%2BQVQGfYiHWLzAZ%2Bd8So6VBbROvmAWY3kmycAxRYI81XGGNFzDgq%2FUqHzQSn2DgsEsn%2FgJ0a1eagLnVB5gGZCnmurn%2F24VFpd%2BLrZLtcfw8ZPjTaBc2yp%2FP2dylLaUiIs1igk95Nx3OKEsZ7qTgPD1s5wZxRIZSz3%2FlZQ0wVz2%2FIl3zc58SMwSlm6Q0kexUprBSa0DrM0%2B76AkwReRtr%2Bsy9Fd82K%2Beah%2BkRA4FZ8%2Bm8NLYWbnz3uPWsEtepTOrIZcREmYyGdfokeewF4%2BYS6I9BaXuiMmQZAbCZb7RY%2FZfAp3G0YSkSnXWU6clcKuPJQxNKsNy5fMVa2K95Mj%2Fk%2BvWHMxNdTpURfW1Fo4bj72UJvpZFzqyb%2Bqk5WzXHj1EWy9TqW9NHFcbOkMaLeQfX1539LkLiIC3%2BdYWu1kkGpoNN3kYWNN9sqn1dRyxMeCZzTwrKTthVWTsu3q9q4STjQpqkQSQ%2BvcI8CW2O79CMfIWMYjN1bxFw5JapY8R6Ytd7zM%2FrS0j9F7EDx0Bha8O2isLRqnxVq8J%2BJ7ySlbD5WecpBq1OPzm9T5atS1T4y6cFRR12uperCkqR5mOrXFzpQ3G5XyzNVjDNobNuU9VX%2FOqPRnHwlwnFG6RGp%2FR6JcyuiTykdHljk4zsgyh%2FZVoibYDsXXsaM6XeZuU%2BZwYJk77ybzLiDbFN9saPEB%2BJv48ld9NOjaRzeufxoB0G0gADRUmwcdPaqHS2Hb%2B3%2FUO37Zeocx304KHrAGTN06E%2B5FsmiqH4v6DD1WPxYfQFe%2F1pRnZQrMxwT202Ppm5Hs2I26Rn%2BVonbForfgCU8tSIBqOaIoTrxfQQLOhwq4512KwFEz6L36FFyql3CymbAE55QborauFYS4MBw%2BRWlKfEPWbKBnPfadEIFZw1y9hrnmQGolRFIq6FBh0z7mzevc%2FBy%2FfMh30GnQMkKvBK3LLFFRUaN5Mf%2FK2f782vMorpWwKeyha9HwI3vIMEbSdIuzu%2FSYsodXUuXOUom5Z00tS6JzMfechV2%2FuM1U38yZyX%2FHdW3YV2CyPpBYXtiWh7YfXGGKQxmCWDImjPYIS5DBEngAQMe1JDgXdec596ae58zmnu1CD3p9AXPgb2PKetJDte%2B59PiVTCtAaZTtC5yVNRk38Ktlv27LyUh7Q340Dst5EX%2Fn25M1BZb51uNns9n%2BCxoGWhUdyQxwTej4ytzNTwtm3sDpnH3sK68hndfkTZXxM%2FzRqa8oDbpedUhlvdC27XpKZGp9I7ah9usin2Mk2iY0Ij9nsNtFjRdA68zCrinkNt9b9Ki09iuLwvH19klW1y4RgndzibJZfjWdK6H89ty%2B%2Fh8%3D))
+
+
+# Overview
+
+Scroll Canvas consists of the following components:
+- [**ProfileRegistry**](../src/profile/ProfileRegistry.sol): A contract for users to mint and query their Canvases.
+- [**Profile**](../src/profile/Profile.sol): Each Canvas is an instance of the profile smart contract.
+- [**EAS**](https://docs.attest.org/docs/welcome): A technology for issuing on-chain attestations.
+- [**ScrollBadgeResolver**](../src/resolver/ScrollBadgeResolver.sol): Each attestation passes through this resolver before the badge is minted. It enforces Canvas badge rules.
+- [**ScrollBadge**](../src/badge/ScrollBadge.sol): Each badge is a contract the conforms to a certain [interface](../src/interfaces/IScrollBadge.sol).
+
+
+## Profiles
+
+Each user can mint a [`Profile`](../src/profile/Profile.sol) instance through [`ProfileRegistry`](../src/profile/ProfileRegistry.sol).
+This contract is the user's Canvas, and minting it is a prerequisite to collecting badges.
+Each wallet can only mint one profile.
+All profiles share the same implementation, upgradable by Scroll to enable new features.
+
+The main use of profiles is personalization.
+Users can configure a username and an avatar.
+Users can also decide which badges they attach to their profile, and in which order they want to display them.
+
+See the [Canvas Interaction Guide](./canvas-interaction-guide.md) section for more details.
+
+
+## ScrollBadge Schema and Resolver
+
+We define a *Scroll badge* [EAS schema](https://docs.attest.org/docs/core--concepts/schemas):
+
+```
+address badge
+bytes   payload
+```
+
+This schema is tied to `ScrollBadgeResolver`.
+Every time a Scroll badge attestation is created or revoked through EAS, `ScrollBadgeResolver` executes some checks and actions.
+After this, it forwards the call to the actual badge implementation.
+
+You can find the schema UID in the [Deployments](./deployments.md) section.
+Browse the Scroll mainnet badge attestations on the [EAS Explorer](https://scroll.easscan.org/schema/view/0xd57de4f41c3d3cc855eadef68f98c0d4edd22d57161d96b7c06d2f4336cc3b49).
+
+
+## Badges
+
+Each badge is an [EAS attestation](https://docs.attest.org/docs/core--concepts/attestations) that goes through the [`ScrollBadgeResolver`](../src/resolver/ScrollBadgeResolver.sol) contract and a badge contract.
+
+Each badge type is a standalone contract that inherits from [`ScrollBadge`](../src/badge/ScrollBadge.sol).
+This badge contract can implement arbitrary logic attached to the attestation.
+Badges implement a `badgeTokenURI` interface, similar to `ERC721.tokenURI`.
+
+Badges are minted to the user's wallet address.
+The user can express their personalization preferences (attach and reorder badges, choose a profile photo) through their Canvas [`Profile`](../src/profile/Profile.sol).
+
+See the [Badges](./badges.md) section for more details, and [Badge Examples](./badge-examples.md) for Solidity code examples.
+
+
+## Explore the Documentation
+
+Explore the following pages to learn more about different aspects of Canvas:
+- [Deployments](./deployments.md) lists the official Canvas contract addresses on Scroll mainnet and on the Scroll Sepolia testnet.
+- [Badges](./badges.md) introduces the basic requirements for badge contracts and lists resources for getting started as a badge developer.
+- [Badge Examples](./badge-examples.md) shows the process of developing custom badges by going through some common examples and use cases.
+- [Canvas Interaction Guide](./canvas-interaction-guide.md) lists common questions and examples for interacting with Canvas profiles and badges.
+- [Official Badges](./official-badges) contains addresses and documentation for some badges issued by Scroll.