Blockscout SDK

Attention ETHGlobal Hackathon Participants. We have a $3000 Bounty available for best SDK Usage (1 $2000 prize and 1 $1000 prize). Add the Blockscout SDK into your app to provide interactivity and instant explorer feedback to your users.

Note: The Blockscout SDK is currently in beta release. Please report any issues on the Blockscout Discord.

Overview

The Blockscout App SDK is a React toolkit designed to integrate Blockscout transaction notifications and transaction history into your decentralized applications (dApps). It provides an easy-to-use interface for displaying transaction status updates and viewing transaction history with real-time updates and mobile-responsive design.

Key Features

  • Transaction Toast Notifications - Real-time transaction status updates with pending, success, and error states

  • Transaction History Popup - View recent transactions for specific addresses or entire chains

  • Transaction Interpretation - Detailed transaction summaries and interpretations

  • Multi-chain Support - Compatible with any blockchain that has a Blockscout explorer instance

  • Mobile-responsive Design - Optimized for both desktop and mobile experiences

Installation

Install the SDK using npm or yarn:

npm install @blockscout/app-sdk
# or
yarn add @blockscout/app-sdk

Transaction Toast Notifications

The transaction toast feature provides real-time notifications for transaction status updates, showing pending, success, and error states with detailed transaction information.

Setup

Wrap your application with the NotificationProvider:

import { NotificationProvider } from "@blockscout/app-sdk";

function App() {
  return (
    <NotificationProvider>
      <YourApp />
    </NotificationProvider>
  );
}

Usage

Use the useNotification hook to display transaction toasts:

import { useNotification } from "@blockscout/app-sdk";

function YourComponent() {
  const { openTxToast } = useNotification();

  const handleTransaction = async (txHash) => {
    try {
      // Your transaction logic here
      await sendTransaction();
      
      // Show transaction toast
      openTxToast("1", txHash); // '1' is the chain ID for Ethereum mainnet
    } catch (error) {
      console.error("Transaction failed:", error);
    }
  };

  return (
    <button onClick={() => handleTransaction("0x123...")}>
      Send Transaction
    </button>
  );
}

Toast Features

  • Real-time status updates (pending, success, error)

  • Transaction interpretation and summaries

  • Links to block explorer

  • Automatic status polling

  • Error handling with revert reasons

Transaction History Popup

The transaction history popup allows users to view recent transactions for a specific address or all transactions on a chain.

Setup

Wrap your application with the TransactionPopupProvider:

import { TransactionPopupProvider } from "@blockscout/app-sdk";

function App() {
  return (
    <TransactionPopupProvider>
      <YourApp />
    </TransactionPopupProvider>
  );
}

Usage

Use the useTransactionPopup hook to open transaction history:

import { useTransactionPopup } from "@blockscout/app-sdk";

function YourComponent() {
  const { openPopup } = useTransactionPopup();

  // Show transactions for a specific address
  const showAddressTransactions = () => {
    openPopup({
      chainId: "1", // Ethereum mainnet
      address: "0x123...", // Optional: specific address
    });
  };

  // Show all transactions for a chain
  const showAllTransactions = () => {
    openPopup({
      chainId: "1", // Ethereum mainnet
    });
  };

  return (
    <div>
      <button onClick={showAddressTransactions}>
        View Address Transactions
      </button>
      <button onClick={showAllTransactions}>
        View All Transactions
      </button>
    </div>
  );
}
  • View recent transactions

  • Filter by address

  • Transaction status indicators

  • Transaction interpretation

  • Links to block explorer

  • Mobile-responsive design

  • Loading states and error handling

Supported Chains

The SDK is compatible with any blockchain that has a Blockscout explorer instance with API v2 support.

Common Supported Chain IDs

  • 1 - Ethereum Mainnet

  • 137 - Polygon Mainnet

  • 42161 - Arbitrum One

  • 10 - Optimism

API Reference

useNotification Hook

const { openTxToast } = useNotification();

// Open a transaction toast
openTxToast(chainId: string, hash: string): Promise<void>

useTransactionPopup Hook

const { openPopup } = useTransactionPopup();

// Open transaction popup
openPopup(options: {
  chainId: string;
  address?: string;
}): void

Complete Integration Example

Here's a complete example showing how to integrate both features:

import React from 'react';
import { 
  NotificationProvider, 
  TransactionPopupProvider,
  useNotification,
  useTransactionPopup 
} from "@blockscout/app-sdk";

function TransactionComponent() {
  const { openTxToast } = useNotification();
  const { openPopup } = useTransactionPopup();

  const sendTransaction = async () => {
    const txHash = "0x123..."; // Your transaction hash
    await openTxToast("1", txHash);
  };

  const viewHistory = () => {
    openPopup({
      chainId: "1",
      address: "0x456..." // Optional
    });
  };

  return (
    <div>
      <button onClick={sendTransaction}>Send Transaction</button>
      <button onClick={viewHistory}>View Transaction History</button>
    </div>
  );
}

function App() {
  return (
    <NotificationProvider>
      <TransactionPopupProvider>
        <TransactionComponent />
      </TransactionPopupProvider>
    </NotificationProvider>
  );
}

export default App;

Last updated

Was this helpful?