[HIP-2] Graph & SDK multichain support

[Jipperism]

Summary

Enable querying hypercerts from multiple chains concurrently, using a single SDK HypercertClient instance.

Abstract

The improvements that are outlined in this proposal will enable

• Querying hypercerts from multiple chains
• Displaying hypercerts when not connected to any chain, from either production or test chains

This will create a more cohesive experience when using the frontend, and prevent confusion by end users when browsing hypercerts they own.

Motivation and rationale

The current implementation only allows for querying the chain that the user is currently connected to. Displaying hypercerts from all available chains will clear up confusion for the end user, for example when connected to the wrong chain. It will also enable new users to browse hypercerts without having to connect their wallet before.

Implementation

Graph

• Deploy the graph under hypercerts-org account so that we can deprecate the hypercerts-admin account: https://thegraph.com/hosted-service/subgraph/hypercerts-org/hypercerts-sepolia.
• Hypercert ids will change from the format of ${contractAddress}-${claimId} to the format of ${chainId}-${contractAddress}-${claimId}. This will ensure that all hypercert ids in the graph remain unique.

SDK

• The hypercert client will be initialized with either a "test" or "production" parameter, which will determine which chains are queried (test: sepolia, production: optimism, celo).
• Write operations will only be possible for the chain the signer (provided at initialization) is connected to.
• Querying multiple chains will be done client side, using and urql middleware implementation.
• An optional parameter chainId: number will be added to the queryParams for all querying methods that return a list of hypercerts.
• A utility method with the function signature isOnChain(chainId: number, hypercertId: string): boolean and will be added to the SDK, to make it easy for developers to determine whether the hypercert is on the specified chain.

Frontend

• Conditionally disable all interaction buttons for hypercerts that live on a different chain than the user is currently connected to (eg. split, merge, transfer buttons).
• "Claim all fractions" button should only mint allowlist entries for the chain the user is currently connected to, and all other allowlist entries should probably be updated to indicate that they won't be minted unless the user connects to the specified chain.
• Update and test all querying components in plasmic.
• Display a chip or banner on all hypercert tiles that shows which chain the hypercert lives on
• Display a chip or banner on all allowlist entries that shows which chain the entry lives on

Infrastructure

• All stored claimIds in supabase will have to be updated with the chain id. We are already keeping track of this so it can be done using either a simple script, or a single SQL query.
• Create script to update hyperboards supabase
• Update defender scripts.

Other things to consider:

• Ensure no code relies on manually splitting the graph claimId on the - character to obtain either the contract address or hypercert id, as this will not work with the new graph hypercert id format.

Operation requirements and ownership

• Plasmic branching functionality will be used to update all required components and test if the changes break any functionality.
• A hypercerts staging db will be setup, and will be cloned from the current production database. Doing this will allow us to update all required fields and test wether any functionality in the frontend breaks before running the update scripts on the production database.

Ownership for this feature will belong to @Jipperism

Links and additional information

Plasmic branching

Example urql middleware implementation:

import {
  makeOperation,
  Operation,
  Exchange,
} from "@urql/core";
import { pipe, tap, map } from "wonka";

// https://github.com/urql-graphql/urql/discussions/1523

const graphUrls = {
  fux: "https://api.thegraph.com/subgraphs/name/bitbeckers/fux-sepolia",
  werk: "https://api.thegraph.com/subgraphs/name/bitbeckers/werk-sepolia",
};

// You can use options for inputs if you want to make this reusable for  the community
export const routeSplitterExchange =
  (): Exchange =>
  ({ forward }) => {
    const processIncomingOperation = (operation: Operation): Operation => {
      if (operation) {
        let url = operation.context.url;

        switch (operation.context.target) {
          case "fux":
            url = graphUrls.fux;
            console.log("Calling fux");
            break;
          case "werk":
            url = graphUrls.werk;
            console.log("Calling werk");
            break;
          default:
            url = graphUrls.fux;
            console.log("Calling default");
            break;
        }

        // your own condition
        return makeOperation(operation.kind, operation, {
          ...operation.context,
          url,
        });
      }

      return operation;
    };

    return (ops$) => {
      return pipe(ops$, map(processIncomingOperation), forward);
    };
  };

Known unknowns:

• Should we do some sort of benchmarking to check performance regression?

Milestones

Week 1

• Deploy new graph instance under hypercerts-org
• Update graph instance with new id format and properties
• Deploy new supabase staging instance
• Setup plasmic branching

Week 2

• Update SDK
• Update defender scripts
• Create supabase hypercerts update script
• Create supabase hyperboards update script

Week 3

• Update frontend
• QA

Week 4

• Rollout

[bitbeckers]

Plasmic branching functionality will be used to update all required components and test if the changes break any functionality.

We should check with @ryscheng if we're enterprise users

Should we do some sort of benchmarking to check performance regression?

Nice idea, could we add this to the GitHub action? Not as a hard fail but we should be alerted on regression in performance. Might be difficult with a fully client side solution tho?

Let's also deploy the updated graphs under hypercerts-org so that we can deprecate the hypercerts-admin account: https://thegraph.com/hosted-service/subgraph/hypercerts-org/hypercerts-sepolia

[ryscheng]

I upgraded us to enabled branching

[ryscheng]

One point that's food for thought ----

Is it possible to keep stronger types whenever possible, i.e. keep it Hypercert IDs in a type
(There's all sorts of parsing bugs that we probably want to avoid if possible.)

{
  chainId,
  contractAddress,
  claimId
}

And then have that reflected in various places. For example for a url, we might have https://hypercerts.org/view/chainId/contractAddress/claimId.

We should also be able to query the Graph in a flexible way, for example:

• Get all hypercerts on this chainId,
• Get hypercerts across all chains with this stable contract address

Then leaves the open question, if when would we absolutely need to have a "serialized" format?
(e.g. ${chainId}-${contractAddress}-${claimId}). We should be very intentional and minimize this probably (or remove if possible)

[bitbeckers]

yes I think that's a good suggestion anywhere outside of the Graph. That implies we'd parse the GraphId into chain, contractAddress and claimId (and can also add validations where needed). In the Graph I'd prefer the pattern already discussed (concatenation) because it enables us to determine the locations of the claim without any other datafield and we won't get conflicts in retrieved datasets.

[bitbeckers]

Updated IDs and deployments in: hypercerts-org/hypercerts#1283