Installation

The easiest way to get started with the React SDK is to use the CLI:

npx web3sdkio create --app

Alternatively, you can install the SDK into your existing project using npm or yarn:

npm install @web3sdkio/react @web3sdkio/sdk ethers

yarn add @web3sdkio/react @web3sdkio/sdk ethers

Getting Started

Our SDK uses a Provider Pattern; meaning any component within the Web3sdkioProvider will have access to the SDK. If you use the CLI to initialize your project, this is already set up for you.

Let's take a look at a typical setup:

Configure the Web3sdkioProvider

Specify the network your smart contracts are deployed to in the desiredChainId prop and wrap your application like so:

import { ChainId, Web3sdkioProvider } from "@web3sdkio/react";

const App = () => {
  return (
    <Web3sdkioProvider desiredChainId={ChainId.Mainnet}>
      <YourApp />
    </Web3sdkioProvider>
  );
};

Below are examples of where to set this up in your application:

Connect to a User's Wallet

Now the provider is set up, we can use all of the hooks and UI components available in the SDK, such as the ConnectWallet component.

Once the user has connected their wallet, all the calls we make to interact with contracts using the SDK will be on behalf of the user.

import { ConnectWallet, useAddress } from "@web3sdkio/react";

export const YourApp = () => {
  const address = useAddress();
  return (
    <div>
      <ConnectWallet />
    </div>
  );
};

The ConnectWallet component handles everything for us, including switching networks, accounts, displaying balances and more.

We can then get the connected address using the useAddress hook anywhere in the app.

Interact With Contracts

Connect to your smart contract using the useContract hook like so:

import { useContract } from "@web3sdkio/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");

  // Now you can use the contract in the rest of the component!
}

You can then use useContractRead and useContractWrite to read data and write transactions to the contract.

You pass the contract object returned from useContract to these hooks as the first parameter and the name of the function (or view/mapping, etc.) on your smart contract as the second parameter. If your function requires parameters, you can pass them as additional arguments.

For example, we can read the name of our contract like so:

import {
  useContract,
  useContractRead,
  useContractWrite,
} from "@web3sdkio/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");
  const { data: name, isLoading: loadingName } = useContractRead(
    contract,
    "name", // The name of the view/mapping/variable on your contract
  );
  const { mutate: setName, isLoading: settingName } = useContractWrite(
    contract,
    "setName", // The name of the function on your contract
  );
}

Using Extensions

Each extension you implement in your smart contract unlocks new functionality in the SDK.

These hooks make it easy to interact with your smart contracts by implementing the complex logic for you under the hood.

For example, if your smart contract implements ERC721Supply, you unlock the ability to view all NFTs on that contract using the SDK; which fetches all of your NFT metadata and the current owner of each NFT in parallel. In the React SDK, that is available using useNFTs:

import { useContract, useNFTs } from "@web3sdkio/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");
  const { data: nfts, isLoading: isReadingNfts } = useNFTs(contract);
}

If we want to mint an NFT and our contract implements ERC721Mintable, we can use the useMintNFT hook to mint an NFT from the connected wallet; handling all of the logic of uploading and pinning the metadata to IPFS for us behind the scenes.

import { useContract, useNFTs, useMintNFT } from "@web3sdkio/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");
  const { data: nfts, isLoading: isReadingNfts } = useNFTs(contract);
  const { mutate: mintNFT, isLoading: isMintingNFT } = useMintNFT(contract);
}

UI Components

The SDK provides many UI components to help you build your application.

For example, we can render each of the NFTs using the NFT Media Renderer component, making use of the loading state from useNFTs:

import { useContract, useNFTs, Web3sdkioNftMedia } from "@web3sdkio/react";

export default function Home() {
  const { contract } = useContract("<CONTRACT_ADDRESS>");
  const { data: nfts, isLoading: isReadingNfts } = useNFTs(contract);

  return (
    <div>
      <h2>My NFTs</h2>
      {isReadingNfts ? (
        <p>Loading...</p>
      ) : (
        <div>
          {nfts.map((nft) => (
            <Web3sdkioNftMedia
              key={nft.metadata.id}
              metadata={nft.metadata}
              height={200}
            />
          ))}
        </div>
      )}
    </div>
  );
}

The Web3Button component ensures the user has connected their wallet and is currently configured to the same network as your smart contract before calling the function. It also has access to the contract directly, allowing you to perform any action on your smart contract when the button is clicked.

For example, we can mint an NFT like so:

import {
  useContract,
  useNFTs,
  Web3sdkioNftMedia,
  Web3Button,
} from "@web3sdkio/react";

const contractAddress = "<CONTRACT_ADDRESS>";
export default function Home() {
  const { contract } = useContract(contractAddress);
  const { data: nfts, isLoading: isReadingNfts } = useNFTs(contract);

  return (
    <div>
      {/* ... Existing Display Logic here ... */}

      <Web3Button
        contractAddress={contractAddress}
        action={(contract) =>
          contract.erc721.mint({
            name: "Hello world!",
            image:
              // You can use a file or URL here!
              "ipfs://QmZbovNXznTHpYn2oqgCFQYP4ZCpKDquenv5rFCX8irseo/0.png",
          })
        }
      >
        Mint NFT
      </Web3Button>
    </div>
  );
}

Advanced Configuration

The Web3sdkioProvider offers a number of configuration options to control the behavior of the React and Typescript SDK.

These are all the configuration options of the <Web3sdkioProvider />. We provide defaults for all of these, but you customize them to suit your needs.

import { ChainId, IpfsStorage, Web3sdkioProvider } from "@web3sdkio/react";

const KitchenSinkExample = () => {
  return (
    <Web3sdkioProvider
      desiredChainId={ChainId.Mainnet}
      chainRpc={{ [ChainId.Mainnet]: "https://mainnet.infura.io/v3" }}
      dAppMeta={{
        name: "Example App",
        description: "This is an example app",
        isDarkMode: false,
        logoUrl: "https://example.com/logo.png",
        url: "https://example.com",
      }}
      storageInterface={new IpfsStorage("https://your.ipfs.host.com")}
      supportedChains={[ChainId.Mainnet]}
      walletConnectors={[
        "walletConnect",
        { name: "injected", options: { shimDisconnect: false } },
        {
          name: "walletLink",
          options: {
            appName: "Example App",
          },
        },
        {
          name: "magic",
          options: {
            apiKey: "your-magic-api-key",
            rpcUrls: {
              [ChainId.Mainnet]: "https://mainnet.infura.io/v3",
            },
          },
        },
      ]}
      sdkOptions={{
        gasSettings: { maxPriceInGwei: 500, speed: "fast" },
        readonlySettings: {
          chainId: ChainId.Mainnet,
          rpcUrl: "https://mainnet.infura.io/v3",
        },
        gasless: {
          openzeppelin: {
            relayerUrl: "your-relayer-url",
          },
        },
      }}
    >
      <YourApp />
    </Web3sdkioProvider>
  );
};