BigBlocks

BigBlocks Provider

Context provider that configures how all BigBlocks hooks fetch data, with web mode for 1sat-stack API and custom mode for desktop RPC, testing, or SSR

Active Configuration

mode: webapiUrl: https://api.1sat.app/1satordfsUrl: https://ordfs.networkgetBalance: nonegetOrdinals: nonegetTokenBalances: nonegetHistory: none

"use client"

import { useCallback, useState } from "react"
import {
  BigBlocksProvider,
  useBigBlocks,
  type BigBlocksBalance,
  type BigBlocksOrdinal,
} from "@/registry/bigblocks/blocks/bigblocks-provider"

// ---------------------------------------------------------------------------
// Inner component that reads context
// ---------------------------------------------------------------------------

function ContextInspector() {
  const { apiUrl, ordfsUrl, getBalance, getOrdinals, getTokenBalances, getHistory } =
    useBigBlocks()

  const hasCustomFetchers =
    !!getBalance || !!getOrdinals || !!getTokenBalances || !!getHistory

  return (
    <div className="rounded-md border border-border bg-muted/50 p-4 font-mono text-sm">
      <p className="mb-2 font-sans font-medium text-foreground">
        Active Configuration
      </p>
      <div className="flex flex-col gap-1 text-muted-foreground">
        <span>
          mode: <strong className="text-foreground">{hasCustomFetchers ? "custom" : "web"}</strong>
        </span>
        <span>apiUrl: {apiUrl}</span>
        <span>ordfsUrl: {ordfsUrl}</span>
        <span>getBalance: {getBalance ? "provided" : "none"}</span>
        <span>getOrdinals: {getOrdinals ? "provided" : "none"}</span>
        <span>getTokenBalances: {getTokenBalances ? "provided" : "none"}</span>
        <span>getHistory: {getHistory ? "provided" : "none"}</span>
      </div>
    </div>
  )
}

// ---------------------------------------------------------------------------
// Demo
// ---------------------------------------------------------------------------

/** Demo showing both web mode and custom mode of BigBlocksProvider */
export function BigBlocksProviderDemo() {
  const [mode, setMode] = useState<"web" | "custom">("web")

  // Simulated custom fetchers for demo purposes
  const mockGetBalance = useCallback(
    async (_address: string): Promise<BigBlocksBalance> => ({
      confirmed: 150000,
      unconfirmed: 5000,
      total: 155000,
    }),
    []
  )

  const mockGetOrdinals = useCallback(
    async (_address: string, _limit?: number): Promise<BigBlocksOrdinal[]> => [
      {
        outpoint: "abc123_0",
        contentType: "image/png",
        name: "Mock Ordinal #1",
        origin: "abc123_0",
      },
    ],
    []
  )

  return (
    <div className="flex flex-col gap-4">
      <div className="flex gap-2">
        <button
          type="button"
          onClick={() => setMode("web")}
          className={`rounded-md px-3 py-1.5 text-sm font-medium transition-colors ${
            mode === "web"
              ? "bg-primary text-primary-foreground"
              : "bg-muted text-muted-foreground hover:bg-accent"
          }`}
        >
          Web Mode
        </button>
        <button
          type="button"
          onClick={() => setMode("custom")}
          className={`rounded-md px-3 py-1.5 text-sm font-medium transition-colors ${
            mode === "custom"
              ? "bg-primary text-primary-foreground"
              : "bg-muted text-muted-foreground hover:bg-accent"
          }`}
        >
          Custom Mode
        </button>
      </div>

      {mode === "web" ? (
        <BigBlocksProvider>
          <ContextInspector />
        </BigBlocksProvider>
      ) : (
        <BigBlocksProvider
          apiUrl="http://localhost:8080/rpc"
          ordfsUrl="http://localhost:9090"
          getBalance={mockGetBalance}
          getOrdinals={mockGetOrdinals}
        >
          <ContextInspector />
        </BigBlocksProvider>
      )}
    </div>
  )
}

Installation

bunx shadcn@latest add https://registry.bigblocks.dev/r/bigblocks-provider.json

Usage

Web Mode (default)

Hooks fetch from the 1sat-stack API. No custom fetchers needed.

import { BigBlocksProvider } from "@/components/blocks/bigblocks-provider"
 
export function App() {
  return (
    <BigBlocksProvider>
      {/* All BigBlocks hooks fetch from the 1sat-stack API */}
      <Dashboard />
    </BigBlocksProvider>
  )
}

Custom Mode

Pass custom fetcher functions for desktop RPC, testing, or SSR:

import { BigBlocksProvider } from "@/components/blocks/bigblocks-provider"
 
export function DesktopApp() {
  return (
    <BigBlocksProvider
      apiUrl="http://localhost:8080/rpc"
      ordfsUrl="http://localhost:9090"
      getBalance={myRpcBalance}
      getOrdinals={myRpcOrdinals}
      onExternalLink={(url) => shell.openExternal(url)}
    >
      <Dashboard />
    </BigBlocksProvider>
  )
}

Accessing Context

Use useBigBlocks in any child component:

import { useBigBlocks } from "@/components/blocks/bigblocks-provider"
 
function MyComponent() {
  const { apiUrl, ordfsUrl, getBalance } = useBigBlocks()
  // ...
}

Props

BigBlocksProvider

Prop	Type	Default	Description
`apiUrl`	`string`	`"https://api.1sat.app/1sat"`	1sat-stack API base URL
`ordfsUrl`	`string`	`"https://ordfs.network"`	ORDFS base URL for on-chain image resolution
`getBalance`	`GetBalanceFn`	--	Custom balance fetcher (bypasses API)
`getOrdinals`	`GetOrdinalsFn`	--	Custom ordinals fetcher (bypasses API)
`getTokenBalances`	`GetTokenBalancesFn`	--	Custom token balance fetcher (bypasses API)
`getHistory`	`GetHistoryFn`	--	Custom transaction history fetcher (bypasses API)
`onExternalLink`	`OnExternalLinkFn`	--	External link handler for desktop apps
`children`	`ReactNode`	required	Child components

Installation Bitcoin Avatar