Blockscout SDK

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.

• Repo: https://github.com/blockscout/app-sdk

• NPM Package https://www.npmjs.com/package/@blockscout/app-sdk

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>
  );
}

Popup Features

• 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.

• Chains are listed in Chainscout.

• Chain IDs can be retrieved from https://github.com/blockscout/chainscout/blob/main/data/chains.json

• To verify if your target chain ID is supported, visit the compatibility checker.

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;