Implementation and Types

Overview of how to start using The Box in your project.

Adding The Box to your project is as easy as importing one React component.

Getting Started

To begin, we'll import The Box from Decent's Box SDK using npm, pnpm or yarn.

npm i @decent.xyz/the-box

Note: The Box is built on wagmi + viem ($npm i wagmi viem), for Solana support, you also need to provide a Solana wallet option in your dapp.

// Import The Box
import { TheBox, ChainId, ActionType } from "@decent.xyz/the-box";

Using The Component

The Box takes in three required props (actionType, actionConfig, apiKey) as well as several optional custom props.

The actionType is the type of transaction you intend to implement (e.g., NftMint, NftFillAsk). Each action type requires a different actionConfig, which are the relevant fields necessary for that transaction. An apiKey for your integration is also required. Get an API key.

For more information on actionTypes and actionArgs, visit The Box Props.

For more information on optional props, visit Optional Props.

Using default settings, The Box renders as a transaction modal to which you can pass parameters dictating transactions to execute. The Box component takes the following types:

<TheBox
  className?: string;
  apiKey: string;
  actionType: 'NftPreferMint' | 'NftMint' |'NftFillAsk';
  paymentButtonText?: string;
  disableLoadingModals?: boolean;
  actionConfig: ActionConfig;
  onTxError?: Function;
  onTxPending?: Function;
  onTxReceipt?: Function;
  onDstTxReceipt?: Function;
  disableGuard?: () => Promise<{ disable: boolean; message: string }>
/>

Please find ActionConfig types on The Box Props page.

Styling

The Box also requires importing a stylesheet to the top of your _app page. Please import it in the first line, above any global CSS stylesheet, to avoid any classes potentially conflicting. See more in the Custom Styling section.

import "@decent.xyz/the-box/index.css"; 

An example configuration to mint a Decent Editions NFT deployed on Arbitrum might look like:

<TheBox
  className="rounded-lg border shadow-md bg-white dark"
  apiKey={process.env.DECENT_API_KEY as string}
  actionType={ActionType.NftMint}
  paymentButtonText="MINT ME"
  actionConfig={{
    contractAddress: '0x3007E0eB44222AC69E1D3c93A9e50F9CA73F53a1',
    chainId: ChainId.ARBITRUM,
    cost: {
      isNative: true,
      amount: parseUnits('0.00005', 18),
    },
  }}
  paymentButtonText="mint pls"
  onTxPending={() => console.log("Initiated transaction 🚀")}
  onTxReceipt={() => console.log("Source transaction confirmed ✅ ")}
  onDstTxReceipt={() => console.log("Destination transaction confirmed ✅")}
  onTxError={(e) => console.log("Transaction failed 😔", e)}
  disableGuard={() => {
    const currentDate = new Date();
    const dayOfWeek = currentDate.getDay();
    return dayOfWeek === 1;
  }} // only enable this NFT Mint button on Monday's: the disable guard enables creative conditions!
/>

API Key Request

Please complete this form to request an API key.

The Box uses API keys to track sales and Box usage from implementing applications.

Finding Contract ABI & Parameters

The transaction method will be defined in each smart contract. To execute a function, you will need to pass the required parameters into The Box's signature property within actionConfig. The easiest way to identify this information is to:

  1. Find a transaction of the same type on the relevant block explorer
  2. Scroll to the bottom to view additional details
  3. Copy the function spotlighted in Input Data
  4. Decode the input data to view the parameters used to execute the function.

You can find additional resources on the Function Signature Help page.


Compatibility with Existing Contracts

The Box is designed to handle all external smart contract interactions. However, The Box's architecture can conflict with some NFT claiming conditions.

For transactions involving a bridge, the Box contract on the destination chain will call the NFT mint function on behalf of the signer and transfer the NFT to the connected wallet or recipient address. Forecasting increasing adoption of relayers and account abstraction, we expect future claim conditions to always accommodate delegated minting. Existing conditions that are not compatible with The Box include:

  • Max Tokens per Wallet: some NFT contracts will limit wallet addresses to a certain number of tokens. Because the Box is calling mint from its address, transactions involving a bridge will be limited to the wallet cap. If the number of transactions involving a bridge exceeds the cap, those requests will revert - even if all transactions are signed from unique wallets. If your NFT contract includes this condition, we strongly recommend removing it to adhere with account abstraction and delegated minting innovations.
  • Some Allowlists: allowlists can require that the allowlisted address call mint. If an allowlisted user attempts to make purchase through the Box that requires a bridge, this form of allowlist will cause the transaction to fail.

Integration Questions?

If you have any integration questions, reach out and a support dev will help!
email: [email protected], twitter: @decentxyz