Client setup

The hypercerts SDK exposes the HypercertClient class that provides a high level interface that communicates with the our API and contracts.

The client handles most complexity involved with minting hypercerts and other contract interactions. Additionally it provides utility methods for common tasks like parsing merkle trees and storing metadata. For reading data from our backend, we recomment connecting to our Graph instance using your prefered graph client.

For validating and uploading metadata and allowlists you can either use the SDK or directly connect to our API

Installation

Install the SDK in your project:

pnpm install @hypercerts-org/sdk

Configuration

Minimal

We recommend using the SDK for utility method and write/upload actions like parsing merkle trees and storing metadata, for example. At a minimum, you need to provide the target environment to initialize the client in read only mode:

type Environment = "production" | "test";

const ENVIRONMENT = "production";

const client = new HypercertClient({environment: ENVIRONMENT});

Connect your wallet

To enable write operations, you need to provide a wallet client:

import { HypercertClient } from "@hypercerts-org/sdk";
import { useWalletClient } from "wagmi";

export const useHypercertClient = () => {
  const { data: walletClient } = useWalletClient();
  const ENVIRONMENT = "production";

  const client = new HypercertClient({
        environment: ENVIRONMENT,
        walletClient,
      }),
    );

  return { client };
};

Bring your RPCs

We use public RPC or RPCs provided by the Hypercerts Foundation for public actions like reading contract state or simulating requests. We infer the client for the public client based on the connected wallet client. You can also explicitly set the public client by passing it in the configuration.

import { HypercertClient } from "@hypercerts-org/sdk";
import { useWalletClient, usePublicClient } from "wagmi";

export const useHypercertClient = () => {
  const { data: walletClient } = useWalletClient();
  const publicClient = usePublicClient()
  const ENVIRONMENT = "production";

  const client = new HypercertClient({
        environment: ENVIRONMENT,
        walletClient,
        publicClient,
      }),
    );

  return { client };
};

See the use-hypercert-client hook in our app for a full implementation.

Setup

When setting up the client, we parse the provided input to infer the applicable hypercert client configuration.

Configuration building

After receiving the configuration, we apply the following logic in getConfig of the SDK to determine your client set up:

1. Input Validation:

   • Check if the config parameter is provided, throw an error if missing.

2. Initial Configuration:

   • Create a base configuration object (_config) by merging: a. Environment settings b. Wallet client settings c. Public client settings d. Graph URL settings e. Deployments for the specified environment (or default)
   • Set the initial readOnly status to true

3. Chain ID Extraction: - Extract the chain ID from the wallet client, if available

4. Writable Chain IDs:

   • Generate a list of chain IDs that support write operations

5. Read-Only Mode Configuration:

   • If no wallet client is provided, log a debug message and keep readOnly as true
   • If a supported chain ID is connected, disable read-only mode and log a debug message

6. Public Client Fallback:

   • If a wallet client is provided but no public client: a. Log a debug message b. Create a default public client using the wallet's chain and HTTP transport

7. Return:

   • Return the final configuration object

Read-only mode

The SDK client will be in read-only mode if any of the following conditions are true:

• The client was initialized without an operator.
• The client was initialized with an operator without signing abilities. If any of these conditions are true, the read-only property of the HypercertClient instance will be set to true, and a warning message will be logged indicating that the client is in read-only mode.

Defaults

The constants.ts file defines various defaults constants that are used throughout the Hypercert system.

DEPLOYMENTS: This constant defines the deployments that are managed by the Hypercert system. Each Deployment object contains information about a specific deployment, including the chain ID, chain name, contract address, and graph name.

For example:

{
  "11155111": {
    "addresses": {
      "HypercertMinterUUPS": "0x1234567890abcdef1234567890abcdef12345678",
      "TransferManager": "0x1234567890abcdef1234567890abcdef12345678",
      "...": "...",
      "StrategyHypercertFractionOffer": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "graphName": "hypercerts-sepola",
    "graphUrl": "https://api.thegraph.com/subgraphs/name/hypercerts-admin/hypercerts-sepolia"
  }
}

You can select which deployment to use by passing in a chainId configuration parameter. We also allow for overrides when creating the SDK by passing configuration variables.

Logging

The logger for the SDK uses the log level based on the value of the LOG_LEVEL environment variable. The log level determines which log messages are printed to the console. By default, the logger is configured to log messages with a level of info or higher to the console.

In your .env file:

LOG_LEVEL="info"

The SDK logger supports four log levels: error, warn, info, and debug.

• The error log level is used to log errors that occur in the SDK.
• The warn log level is used to log warnings that do not necessarily indicate an error, but may be important to investigate.
• The info log level is used to log general information about the SDK's state or behavior.
• The debug log level is used to log detailed information that is useful for debugging purposes.