@boostxyz/reward-kit-react

• Documentation

RewardKit by Boost makes it easy for any React app to add Boost functionality and empower the distribution of tokens for actions.

[!WARNING] This library is in early alpha and subject to breaking changes.

Installation

npm i @boostxyz/reward-kit-react
# OR
pnpm add @boostxyz/reward-kit-react

Basic Usage

'use client'
import { RewardKitProvider, RewardKitButton, RewardKitConfig } from "@boostxyz/reward-kit-react";

// Optional configuration used for filtering shown Boosts at an appplication-wide level
const config: RewardKitConfig = {
  // Enable testnets / staging API
  testnetsEnabled?: boolean,
  // The preconfigured creator address, if any, to filter displayed rewards
  creatorAddress?: Address,
  // The preconfigured Boost ID, if any
  boostId?: string,
  // Only show offers from Boosts funded by this budget account
  budgetAccount?: Address,
  // Only show offers with actions that target a contract on this chain ID. You must specify this if also specifying `targetContract`
  chainId?: number,
  // Only show offers with actions that target this contract address. If specifying, you must also specify chainId
  targetContract?: Address,
  // Only show offers with actions targeting tokens, in the format `chainId:address`, or `chainId:address:tokenId`
  tokens?: (`${number}:${Address}` | `${number}:${Address}:${number}`)[]
  // Callback function for wallet connection
  onConnectWalletClick?: () => void,
}

function App() {
  return (
    <RewardKitProvider
      defaultOpen={false}
      // Initial theme
      theme={myCustomTheme || undefined}
      // Specifying config
      config={config}
    >
      <div>
        <RewardKitButton>See Rewards</RewardKitButton>
      </div>
    </RewardKitProvider>
  );
}

CSP Configuration for Boost API

If you have a strict CSP policy, you may have to explicitly allow https://api-v2.boost.xyz and/or https://api-v2-staging.boost.xyz

For example, you can configure your headers as follows:

Content-Security-Policy: connect-src https://api-v2.boost.xyz https://api-v2-staging.boost.xyz/;
// or
Content-Security-Policy: default-src https://api-v2.boost.xyz https://api-v2-staging.boost.xyz/;

API Overview

RewardKit provides a set of components and hooks to integrate token distribution functionality into your application. Below is an overview of the main components and hooks available:

Components

• RewardKitButton: A customizable button component that triggers the reward modal.
• RewardKitProvider: A context provider that supplies theme data to RewardKit components.

Hooks

• useRewardKit: A custom hook that provides methods to control the reward modal's visibility if you want to use completely custom logic instead of the provided RewardKitButton
• useClaimIncentives: A mutation hook that when executed, attempts to claim a Boost incentive using a given signature and claimant address.
• useTokenBalances: A data fetching hook that queries known token balances across configurable chain ID's or Boost Protocol chains.
• useRewardKitProfile: A data fetching hook that retrieves active Boosts, claimed Boosts, claimable Boosts, and total claim amounts for a given RewardKitConfig configuration.
• useRewardKitBoost: A data fetching hook that retrieves details on a single Boost, including claimability given an ID and claimant address.
• useRewardKitBoosts: A data fetching hook that retrieves a list of Boosts and their claimability given an optional RewardKitConfig configuration
• useClaimSignatures: A data fetching hook that retrieves signatures to be used in conjunction with useClaimIncentives, or throws if inelligible for claims
• useClaimableBoostsCount: A data fetching hook that retrieves the amount of claimable Boosts for a given creatorAddress and optional additional configuration

function Component() {
  // Access the current RewardKit context
  const rewardKit = useRewardKit()

  // reads currently applied colors scheme
  rewardKit.theme
  // Is the modal currently open.
  rewardKit.isModalOpen
  // See RewardKitConfig interface, contains several optional parameters supplied to the API when requesting Boosts to display
  rewardKit.config
  // Call this to update RewardKit theme variables
  rewardKit.changeTheme({ primary: '#fff', ...})
  // Open the modal with the current theme and configuration
  rewardKit.openModal()
  // Close the modal
  rewardKit.closeModal()
  // Toggle the modal's visibility
  rewardKit.toggleModal()
  // Reconfigure RewardKit to update either the "boostId" and/or "deployerAddress'
  rewardKit.configure({ boostId: '', deployerAddress: '0x' })
}

RewardKitButton

The RewardKitButton is a component that allows users to easily integrate token distribution functionality into their app. Here's how you can use it:

1. Import the Component: First, import the RewardKitButton into your project.

import { RewardKitButton } from "@boostxyz/reward-kit-react";

2. Add the Button to Your Component: Use the RewardKitButton in your component's render method.

function MyComponent() {
  return (
    <div>
      <h1>Welcome to My App</h1>
      <RewardKitButton />
    </div>
  );
}

3. Customize: The RewardKitButton is completely customizable and takes any prop a normal button could take.

// using shad-cn buttons, the RewardKitButton here inherits all of the classes automatically
<Button variant="secondary" size="sm" asChild>
  <RewardKitButton />
</Button>

Theming RewardKit

RewardKit allows you to customize its appearance by providing a theme object. This is done through the RewardKitProvider component, which uses the React Context API to pass theme data to its child components.

How to Apply a Theme

1. Define Your Theme: Create a theme object that specifies your custom styles. You can override any of the default theme values. Your custom theme will be merged with the default, in case you only want to override a few values.

const myCustomTheme = {
   accent: "#9a75ff",
   primary: "#25292e",
   "primary-foreground": "#fff",
   secondary: "#989fa9",
   card: "#f6f7f9",
   dialog: "#fff",
   "dialog-border": "#e5e7eb",
   "dialog-overlay": "rgba(0, 0, 0, 0.2)",
   skeleton: "#f7f6f8",
   dim: "#f7f6f8",
   scrollbar: '##989fa9',
   'button-primary': '#25292e',
   'button-secondary': "#f6f7f9',
};

2. Wrap Your Application with RewardKitProvider: Use the RewardKitProvider to apply your theme to the RewardKit components.

'use client'
import { RewardKitProvider } from "@boostxyz/reward-kit-react";

function App() {
  return (
    <RewardKitProvider theme={myCustomTheme}>
      <MyComponent />
    </RewardKitProvider>
  );
}

Default Theme

If no theme is provided, RewardKit uses a default theme. You can view and modify the default theme by checking the defaultTheme object in the source code.

By following these steps, you can easily customize the look and feel of RewardKit to match your application's design requirements.

Wallet Connection Integration (Optional)

When a user isn't connected to a wallet, RewardKit displays a prompt in place of wallet-dependent features. You can optionally provide a way for users to connect their wallet directly from within the RewardKit interface.

How it works:

• The onConnectWalletClick callback in the configuration is optional.
• When provided, a "Connect Wallet" button will be displayed in the RewardKit modal if the user is not connected.
• If this callback is not included, the prompt will simply instruct the user to connect their wallet, but without a button.
• RewardKit functions properly with or without this callback; it serves as a UI enhancement rather than a requirement.

import { RewardKitProvider } from "@boostxyz/reward-kit-react";
// Import your wallet connection library
import { useConnectModal } from '@rainbow-me/rainbowkit';

function App() {
  // Get the connection modal function from your wallet library
  const { openConnectModal } = useConnectModal();
  
  return (
    <RewardKitProvider
      config={{
        // Your other configuration...
        onConnectWalletClick: openConnectModal,
      }}
    >
      <YourApp />
    </RewardKitProvider>
  );
}