Canvas & Badge Integration Guide

We are thrilled to have you join us in building unique badges on Scroll Canvas, a product designed for ecosystem projects to interact with users in a more personal way on-chain.

Background

Canvas

Each Canvas is a Profile smart contract, minted by the users through the ProfileRegistry contract on Scroll. Canvas is not transferrable and unique to each wallet. (You can check out Canvas contracts here)

Canvas is an open onchain profile database of user identities and achievements (check out dashboard built by community on Dune).

Badge

Badges are attestations of identities, achievements and traits issued through the Ethereum Attestation Service permissionlessly by different ecosystem projects. Badges are wallet-bound and non-transferable. Badges facilitate interactions between ecosystem projects and users.

Developers can issue badges in three methods:

Developers can design badges in two ways:

Before you Start

Badge issuance and deployment of the contract is fully permissionless. Please follow the steps below to issue a Badge for your project.

Step 1 Design: Badge Design Guidelines

Visual Format Request:

• Minimum resolution: 480px x 480px
• Optimal resolution: 600px x 600px
• File size: Under 300KB

Decide on Badge Details

Step 2 Engineering: Deploying Badges & Go Live

1. Understand Canvas and Badges: Read through this guide and understand how Canvas and Badges work together.

2. Develop and Deploy Badge Contract (link to deployment contracts): Ensure it is verified on Scrollscan. For backend-authorized badges, you also need to deploy an AttesterProxy

3. For backend-authorized badges, set up Check and Claim APIs. For gifted badges, set up Check API: Check eligibility and claim eligibility using provided schemas, confirm correct cross-origin configuration.

   Reference: Check and Claim API

   Check Eligibility For Minting Badge

   1. method: GET

   2. url: {{pathname}}/check?badge={{badgeContractAddress}}&recipient={{walletAddress}}

   3. contentType: data/json

   4. responseSchema

      // eligible
      {
        code: 1,
        message: "success",
        eligibility: true
      }
      
      // not eligible
      {
        code: 0,
        message: "why the recipient is not eligible",
        eligibility: false
      }
      
      // error
      // http code is not 200

   Claim Badge

   1. method: GET

   2. url: {{pathname}}/claim?badge={{badgeContractAddress}}&recipient={{walletAddress}}

   3. contentType: data/json

   4. responseSchema

      // success
      {
        code: 1,
        message: "success",
        tx: ...
      }
      
      // failure
      {
        code: 0,
        message: "some msg",
      }
      
      // error
      // http code is not 200

4. Access Readiness: Ensure your badge contract implements ScrollBadgeDefaultURI, allowing retrieval of default display data (name, image, description, issuerName ) via bytes32(0) with informative name and description.

5. Set up support: Prepare a channel for your badge holders can find you for support, get the url to join that channel ready.

Step 3 Test: Sanity Check

1. Once your badge has been deployed on Scroll, you can auto-check some (but not all) of these requirements by running yarn check-badge (link to check badge script).

   • If your badge minting transaction reverts, we recommend debugging using cast:

   cast run --rpc-url https://rpc.scroll.io [txhash]

   This call will simulate the transaction in a local environment and show you the call stack and revert reason.

   • For badgeTokenURI link returned, ensure correct cross-origin configuration
   Reference: CORS

   CORS

   Please ensure the provided API supports the cross-origin requirements.

   Sepolia

   • localhost: This allows for development and testing directly from your local machine environment.
   • Domains containing the substring ‘scroll’: Any domain that includes the substring ‘scroll’ in its name is allowed to make requests.

   Mainnet

   • scroll.io domain: requests originating from scroll.io are permitted.

2. Review the information on the badge detail page:

   • Confirm that all basic badge information and redirect links are correct and match the information you provided.
   • Verify that the check API is operational. Test it with 2-4 wallet addresses eligible/ineligible to mint this badge and confirm that the claim API is functioning properly.
   • If you have created a badge that can be upgraded, please use wallets that meet different level requirements to attempt minting it. Ideally, find at least one wallet per level requirement to ensure the badge mints correctly.

3. To maintain the availability of the check API and claim API, Scroll recommends maintaining a TPS of approximately 300. Adjust this rate accordingly if your API handles multiple badges simultaneously.

4. If your badge image is stored on IPFS, due to the distributed nature of IPFS, the request time for users in different regions to access content on IPFS can be unpredictable. If they want a better user experience, they can self-host the content.

Step 4 Announce: Reveal Your Badge

1. To get the word out faster, you are encouraged to embed badge mint and discovery in your product! Scroll provides an example code for anthropomorphic “assistants” to pop up when the user meets the badge minting requirements.

   Scroll Canvas - Anthropomorphic “assistants” Integration Guide for Developers

2. Share on social media about your badge launch and the eligibility criteria. Use #BadgeonScroll and tag @Scroll_ZKP to boost more visibility.

3. Monitor your community / support channel for user feedback. If there is any Canvas backend related issues, please reach out to Scroll Discord channel.