zuno-marketplace-sdk

v2.1.2

Published

a month ago

All-in-One NFT Marketplace SDK with Wagmi & React Query built-in

0High
0Medium
0Low

qdang46

nft marketplace web3 ethereum wagmi react-query sdk blockchain smart-contracts

Zuno Marketplace SDK

All-in-One NFT Marketplace SDK with Wagmi & React Query built-in

A comprehensive, type-safe SDK for building NFT marketplace applications on Ethereum and EVM-compatible chains. Built with TypeScript, featuring first-class React support with Wagmi and TanStack Query integration.

Features

Complete NFT Marketplace - Exchange, Auctions, Offers, Bundles
React Integration - 21+ hooks with Wagmi & React Query
Type-Safe - Full TypeScript support with strict typing
Smart Caching - Built-in ABI caching with TanStack Query
Modular Design - Use only what you need
Production Ready - Robust error handling and retries
DevTools - In-app debugging panel

Platform Support

| Feature | Status | Description | | --------------- | :----: | ------------------------------------------------ | | Zuno ABIs | ✅ | Fully supported with built-in registry | | Zuno Contracts | ✅ | Full integration with Zuno marketplace contracts | | Other ABIs | ❌ | Not supported yet | | Other Contracts | ❌ | Custom contract support not available |

Network Support

| Network | Status | Chain ID | Description | | ----------------- | :----: | :-------: | ------------------------------ | | Local Development | ✅ | 31337 | Full support for local testing | | Testnet (Sepolia) | ⚠️ | 11155111 | Planned for Q1 2026 | | Ethereum Mainnet | ⚠️ | 1 | Planned for Q2 2026 |

🆕 What's New in v2.1.1

✨ v2.1.1 Features

ERC1155 Listing Support - Full support for ERC1155 NFT listings with configurable amounts
Auto Token Detection - Automatic detection of ERC721 vs ERC1155 token standards
Enhanced Validation - Comprehensive validation for amount parameters
Backward Compatible - ERC721 listings continue to work without changes

✨ v2.1.0 Features

WagmiProviderSync & SSR Support - Sync provider state with SSR-safe initialization
Transaction Retry Logic - Enhanced transactionStore with retry and history tracking
Batch Progress Events - Real-time progress updates for batch operations
ListingId Validation - Strict bytes32 format validation for listing IDs
Dutch Auction Warnings - Warning logs for price clamp adjustments

⚡️ Performance Improvements

Approval Caching - Reduced RPC calls with approval status caching
LogStore Optimization - Better performance under high-frequency logging

📖 v2.0.0 Features

Batch Auction Operations

// Batch create English auctions (max 20 per tx)
const { auctionIds, tx } = await sdk.auction.batchCreateEnglishAuction({
  collectionAddress: "0x...",
  tokenIds: ["1", "2", "3"],
  startingBid: "1.0",
  duration: 86400 * 7,
});

// Batch cancel auctions
const { cancelledCount, tx } = await sdk.auction.batchCancelAuction([
  "1",
  "2",
  "3",
]);

📖 Allowlist Management

// Add addresses to allowlist
await sdk.collection.addToAllowlist({
  collectionAddress: "0x...",
  addresses: ["0x...", "0x..."],
});

// Enable allowlist-only mode (permanent restriction)
await sdk.collection.setAllowlistOnly({
  collectionAddress: "0x...",
  enabled: true,
});

// Check allowlist status
const isAllowed = await sdk.collection.isInAllowlist({
  collectionAddress: "0x...",
  address: "0x...",
});

v2.0.0 Highlights

Tree-shakeable imports for smaller bundles
Testing utilities (zuno-marketplace-sdk/testing)
DevTools component for visual debugging
Standalone logger module

📦 Installation

npm install zuno-marketplace-sdk ethers@6 @tanstack/react-query wagmi viem

Quick Start

React with Next.js

// app/layout.tsx
import { ZunoProvider } from "zuno-marketplace-sdk/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ZunoProvider
          config={{
            apiKey: process.env.NEXT_PUBLIC_ZUNO_API_KEY!,
            network: "sepolia",
          }}
        >
          {children}
        </ZunoProvider>
      </body>
    </html>
  );
}

// app/page.tsx
"use client";

import { useExchange, useWallet } from "zuno-marketplace-sdk/react";

export default function HomePage() {
  const { address, connect, isConnected } = useWallet();
  const { listNFT } = useExchange();

  const handleList = async () => {
    const { listingId, tx } = await listNFT.mutateAsync({
      collectionAddress: "0x...",
      tokenId: "1",
      price: "1.5",
      duration: 86400,
    });
    console.log("Listed:", listingId);
  };

  return (
    <div>
      {!isConnected ? (
        <button onClick={() => connect()}>Connect</button>
      ) : (
        <button onClick={handleList}>List NFT</button>
      )}
    </div>
  );
}

Core Modules

Exchange

// List ERC721 NFT (backward compatible)
const { listingId, tx } = await sdk.exchange.listNFT({
  collectionAddress: "0x...",
  tokenId: "1",
  price: "1.5",
  duration: 86400,
});

// List ERC1155 NFT with amount
const { listingId: erc1155Listing } = await sdk.exchange.listNFT({
  collectionAddress: "0x...",
  tokenId: "1",
  amount: "10",  // List 10 tokens
  price: "1.5",
  duration: 86400,
});

// Batch list ERC1155 with amounts
const { listingIds } = await sdk.exchange.batchListNFT({
  collectionAddress: "0x...",
  tokenIds: ["1", "2", "3"],
  amounts: ["5", "10", "15"],
  prices: ["1.0", "2.0", "3.0"],
  duration: 86400,
});

// Buy NFT
const { tx } = await sdk.exchange.buyNFT({ listingId: "0x..." });

// Cancel listing
await sdk.exchange.cancelListing("0x...");

// Get listing with amount (ERC1155)
const listing = await sdk.exchange.getListing("0x...");
console.log(listing.amount); // "10" for ERC1155, undefined for ERC721

Note: See ERC1155 Listing Guide for detailed documentation on ERC1155 support.

Collection

// Create ERC721 collection
const { address, tx } = await sdk.collection.createERC721Collection({
  name: "My NFTs",
  symbol: "MNFT",
  maxSupply: 10000,
  mintPrice: "0.1",
  royaltyFee: 500,
  tokenURI: "ipfs://...",
});

// Mint NFT
const { tokenId, tx } = await sdk.collection.mintERC721({
  collectionAddress: "0x...",
  recipient: "0x...",
  value: "0.1",
});

// Allowlist management
await sdk.collection.addToAllowlist({
  collectionAddress: "0x...",
  addresses: ["0x...", "0x..."],
});

Auction

// Create English auction
const { auctionId, tx } = await sdk.auction.createEnglishAuction({
  collectionAddress: "0x...",
  tokenId: "1",
  startingBid: "1.0",
  duration: 86400 * 7,
});

// Create Dutch auction
const { auctionId, tx } = await sdk.auction.createDutchAuction({
  collectionAddress: "0x...",
  tokenId: "1",
  startPrice: "10.0",
  endPrice: "1.0",
  duration: 86400,
});

// Place bid
const { tx } = await sdk.auction.placeBid({
  auctionId: "1",
  amount: "1.5",
});

// Batch operations
const { auctionIds, tx } = await sdk.auction.batchCreateEnglishAuction({
  collectionAddress: "0x...",
  tokenIds: ["1", "2", "3"],
  startingBid: "1.0",
  duration: 86400 * 7,
});

React Hooks

import {
  useExchange,
  useCollection,
  useAuction,
  useWallet,
  useZunoSDK,
  useZunoLogger,
} from "zuno-marketplace-sdk/react";

function App() {
  const { listNFT, buyNFT } = useExchange();
  const { createERC721, mintERC721 } = useCollection();
  const { createEnglishAuction, placeBid } = useAuction();
  const { address, connect } = useWallet();
  const sdk = useZunoSDK();
  const logger = useZunoLogger();

  logger.info("App rendered");
  return <div>Network: {sdk.getConfig().network}</div>;
}

SDK Access Patterns

React Components

import { useZunoSDK, useZunoLogger } from "zuno-marketplace-sdk/react";

function MyComponent() {
  const sdk = useZunoSDK();
  const logger = useZunoLogger();
  return <div>Network: {sdk.getConfig().network}</div>;
}

Non-React Contexts

import { ZunoSDK, getSdk, getLogger } from "zuno-marketplace-sdk";

// Initialize once
ZunoSDK.getInstance({
  apiKey: process.env.ZUNO_API_KEY!,
  network: "sepolia",
});

// Use anywhere
const sdk = getSdk();
const logger = getLogger();

Logging & DevTools

Zuno DevTools

import { ZunoDevTools } from "zuno-marketplace-sdk/react";

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === "development" && (
        <ZunoDevTools
          config={{
            showLogger: true,
            showTransactions: true,
            showCache: true,
            showNetwork: true,
            position: "bottom-right",
          }}
        />
      )}
    </>
  );
}

Logger Configuration

const sdk = new ZunoSDK({
  apiKey: "xxx",
  network: "sepolia",
  logger: {
    level: "debug", // 'none' | 'error' | 'warn' | 'info' | 'debug'
    timestamp: true,
    modulePrefix: true,
    logTransactions: true,
    customLogger: {
      info: (msg, meta) => myLogger.info(msg, meta),
      error: (msg, meta) => Sentry.captureException(new Error(msg)),
    },
  },
});

Documentation

Project Overview & PDR - Project overview and requirements
Codebase Summary - Architecture and module organization
Code Standards - TypeScript and coding conventions
System Architecture - Detailed architecture documentation

Development

npm install          # Install dependencies
npm run build        # Build package
npm run type-check   # Check types
npm run lint         # Lint code
npm run test         # Run tests

License

Made with ❤️ by the Zuno Team