spark-micropayments 0.2.0

package/ReadMe.md

@@ -0,0 +1,38 @@
+## Overview
+To install the package, you can run `npm i micropayments` in your project.
+
+To use the micropayments package, you can use the following code:
+
+```tsx
+import Paywall from 'micropayments'
+
+function App() {
+  return (
+    <div>
+      <h1>Welcome to my webpage</h1>
+      <p>Here is free content that is visible to everyone</p>
+
+      <Paywall
+        receiverSparkAddress="spark1pgss96dw2dqw0gwxlwudx2v863husuass6u2q3e4lfz23qs96ewfedz2w0pxam"
+        amount={0.1}
+        sparkscanApiKey="ss_sk_live_..."
+      >
+        <p>Here is some content that is only visible if you pay 0.1 USDB</p>
+      </Paywall>
+    </div>
+  )
+}
+```
+
+Any content within the `Paywall` component will only be visible if the user pays the specified amount of USDB via the Spark network. The user connects their Xverse wallet and pays using USDB stablecoin.
+
+## Parameters
+
+#### receiverSparkAddress
+The Spark address that will receive USDB payments. This is the address of the content owner.
+
+#### amount
+The minimum amount of USDB that the user needs to pay to access the paywalled content (e.g., 0.1 = $0.10).
+
+#### sparkscanApiKey
+Your SparkScan API key, used to verify whether the connected wallet has already paid.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+interface ConnectWalletProps {
+    className?: string;
+}
+export declare function ConnectWallet({ className }: ConnectWalletProps): import("react/jsx-runtime").JSX.Element | null;
+interface PaywallProps {
+    children: React.ReactNode;
+    receiverSparkAddress: string;
+    amount: number;
+    sparkscanApiKey: string;
+    /** Base URL for SparkScan API. Use a proxy path (e.g. '/api/sparkscan') to avoid CORS issues. Defaults to 'https://api.sparkscan.io'. */
+    sparkscanBaseUrl?: string;
+}
+export default function Paywall({ children, receiverSparkAddress, amount, sparkscanApiKey, sparkscanBaseUrl, }: PaywallProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/index.js

@@ -0,0 +1,207 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+// index.tsx (Micropayments - Spark/USDB)
+// Paywall component using Xverse wallet (sats-connect) and SparkScan API
+import { useState, useEffect, useSyncExternalStore } from 'react';
+import { request, AddressPurpose } from 'sats-connect';
+const SPARKSCAN_API = 'https://api.sparkscan.io';
+const USDB_TOKEN_ID = 'btkn1xgrvjwey5ngcagvap2dzzvsy4uk8ua9x69k82dwvt5e7ef9drm9qztux87';
+let _walletAddress = localStorage.getItem('spark_address');
+const _listeners = new Set();
+function getWalletAddress() {
+    return _walletAddress;
+}
+function setWalletAddress(addr) {
+    _walletAddress = addr;
+    if (addr)
+        localStorage.setItem('spark_address', addr);
+    else
+        localStorage.removeItem('spark_address');
+    _listeners.forEach((fn) => fn());
+}
+function subscribe(fn) {
+    _listeners.add(fn);
+    return () => { _listeners.delete(fn); };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function formatAmountDisplay(amount) {
+    if (amount < 1) {
+        const cents = Math.round(amount * 100);
+        return {
+            display: `${cents} cent${cents !== 1 ? 's' : ''}`,
+            usdc: `${amount} USDB`,
+        };
+    }
+    else {
+        return {
+            display: `$${amount}`,
+            usdc: `${amount} USDB`,
+        };
+    }
+}
+async function checkExistingPayment(sparkAddress, recipientAddress, requiredAmount, apiKey, baseUrl) {
+    try {
+        const isUSDB = (tx) => tx.tokenMetadata?.tokenAddress === USDB_TOKEN_ID ||
+            tx.tokenMetadata?.tokenIdentifier === USDB_TOKEN_ID;
+        const minRawAmount = (tx) => requiredAmount * 10 ** (tx.tokenMetadata?.decimals ?? 0);
+        // Check if recipient received >= requiredAmount in the tx's outputs
+        const recipientGotPaid = (tx) => {
+            const minRaw = minRawAmount(tx);
+            if (tx.type === 'token_transfer') {
+                const raw = parseFloat(tx.tokenAmount ?? '');
+                return !isNaN(raw) && raw >= minRaw;
+            }
+            if (tx.type === 'token_multi_transfer') {
+                return (tx.multiIoDetails?.outputs ?? []).some((o) => o.address === recipientAddress &&
+                    parseFloat(o.amount) >= minRaw);
+            }
+            return false;
+        };
+        const fetchTxs = async (address) => {
+            const r = await fetch(`${baseUrl}/v1/address/${address}/transactions?network=MAINNET&limit=100`, { headers: { 'X-API-Key': apiKey } });
+            if (!r.ok)
+                return [];
+            const json = await r.json();
+            return json.data ?? [];
+        };
+        const isConfirmedUSDB = (tx) => tx.status === 'confirmed' && isUSDB(tx) && recipientGotPaid(tx);
+        // 1. Query user's transactions
+        const userTxs = await fetchTxs(sparkAddress);
+        // Outgoing token_transfer to recipient
+        if (userTxs.some((tx) => tx.type === 'token_transfer' &&
+            tx.direction === 'outgoing' &&
+            tx.counterparty?.identifier === recipientAddress &&
+            isConfirmedUSDB(tx)))
+            return true;
+        // token_multi_transfer where user is in inputs and recipient is in outputs
+        if (userTxs.some((tx) => tx.type === 'token_multi_transfer' &&
+            isConfirmedUSDB(tx) &&
+            (tx.multiIoDetails?.inputs ?? []).some((i) => i.address === sparkAddress)))
+            return true;
+        // 2. If user IS the recipient, any incoming USDB payment counts
+        if (sparkAddress === recipientAddress &&
+            userTxs.some((tx) => (tx.type === 'token_transfer' || tx.type === 'token_multi_transfer') &&
+                tx.direction === 'incoming' &&
+                isConfirmedUSDB(tx)))
+            return true;
+        // 3. Fallback: query recipient's transactions for a payment from this user
+        if (sparkAddress !== recipientAddress) {
+            const recipTxs = await fetchTxs(recipientAddress);
+            // Incoming token_transfer from user
+            if (recipTxs.some((tx) => tx.type === 'token_transfer' &&
+                tx.direction === 'incoming' &&
+                tx.counterparty?.identifier === sparkAddress &&
+                isConfirmedUSDB(tx)))
+                return true;
+            // token_multi_transfer where user is in inputs
+            if (recipTxs.some((tx) => tx.type === 'token_multi_transfer' &&
+                isConfirmedUSDB(tx) &&
+                (tx.multiIoDetails?.inputs ?? []).some((i) => i.address === sparkAddress)))
+                return true;
+        }
+        return false;
+    }
+    catch (err) {
+        console.error('Payment check failed', err);
+        return false;
+    }
+}
+export function ConnectWallet({ className }) {
+    const walletAddress = useSyncExternalStore(subscribe, getWalletAddress);
+    const handleDisconnect = () => {
+        setWalletAddress(null);
+    };
+    if (!walletAddress)
+        return null;
+    return (_jsx("div", { className: className, children: _jsxs("div", { className: "micropay-wallet-info", children: [_jsxs("span", { className: "micropay-wallet-address", children: [walletAddress.slice(0, 12), "\u2026", walletAddress.slice(-6)] }), _jsx("button", { onClick: handleDisconnect, className: "micropay-disconnect-button", children: "Disconnect" })] }) }));
+}
+export default function Paywall({ children, receiverSparkAddress, amount, sparkscanApiKey, sparkscanBaseUrl = SPARKSCAN_API, }) {
+    const walletAddress = useSyncExternalStore(subscribe, getWalletAddress);
+    const [paid, setPaid] = useState(false);
+    const [paying, setPaying] = useState(false);
+    const [connecting, setConnecting] = useState(false);
+    const [checking, setChecking] = useState(true);
+    const [error, setError] = useState(null);
+    const formattedAmount = formatAmountDisplay(amount);
+    // Check for existing payment whenever the wallet address changes
+    useEffect(() => {
+        if (walletAddress) {
+            setChecking(true);
+            checkExistingPayment(walletAddress, receiverSparkAddress, amount, sparkscanApiKey, sparkscanBaseUrl).then((hasPaid) => {
+                if (hasPaid)
+                    setPaid(true);
+                setChecking(false);
+            });
+        }
+        else {
+            setPaid(false);
+            setChecking(false);
+        }
+    }, [walletAddress, receiverSparkAddress, amount, sparkscanApiKey, sparkscanBaseUrl]);
+    const handleConnect = async () => {
+        setConnecting(true);
+        setError(null);
+        try {
+            const connectRes = await request('wallet_connect', {
+                addresses: [AddressPurpose.Spark],
+                message: 'Connect to access this content',
+            });
+            if (connectRes.status !== 'success') {
+                setError('Wallet connection was declined.');
+                setConnecting(false);
+                return;
+            }
+            const sparkAddr = connectRes.result.addresses?.find((a) => a.purpose === 'spark')?.address;
+            if (!sparkAddr) {
+                setError('No Spark address found in wallet.');
+                setConnecting(false);
+                return;
+            }
+            setWalletAddress(sparkAddr);
+        }
+        catch (err) {
+            setError('Could not connect to wallet. Is Xverse installed?');
+            console.error('Wallet connect error', err);
+        }
+        finally {
+            setConnecting(false);
+        }
+    };
+    const handlePay = async () => {
+        if (!walletAddress)
+            return;
+        setPaying(true);
+        setError(null);
+        try {
+            const payRes = await request('spark_transferToken', {
+                receiverSparkAddress,
+                tokenIdentifier: USDB_TOKEN_ID,
+                tokenAmount: amount,
+            });
+            if ('result' in payRes) {
+                setPaid(true);
+            }
+            else {
+                setError('Payment was not completed.');
+            }
+        }
+        catch (err) {
+            setError(err?.message || 'Payment failed.');
+            console.error('Payment error', err);
+        }
+        finally {
+            setPaying(false);
+        }
+    };
+    // Still checking payment status on mount
+    if (checking) {
+        return (_jsx("div", { className: "micropay-container", children: _jsx("p", { className: "micropay-checking", children: "Checking payment status\u2026" }) }));
+    }
+    // Paid — show content
+    if (paid) {
+        return _jsx(_Fragment, { children: children });
+    }
+    // Not paid — show paywall
+    return (_jsxs("div", { className: "micropay-container", children: [_jsx("div", { className: "connectkit-button-container micropay-connect-container", children: _jsxs("div", { className: "connectkit-button micropay-connect", children: [_jsxs("p", { className: "micropay-instructions", children: ["To continue, please pay ", formattedAmount.display, " (", formattedAmount.usdc, ") on the Spark network."] }), !walletAddress && (_jsx("button", { onClick: handleConnect, disabled: connecting, className: "pay-button micropay-pay-button", children: connecting ? 'Connecting…' : 'Connect Wallet' }))] }) }), walletAddress && (_jsx("div", { className: "pay-button-container micropay-pay-container", children: _jsx("button", { onClick: handlePay, disabled: paying, className: "pay-button micropay-pay-button", children: paying ? 'Processing…' : `Pay ${formattedAmount.usdc}` }) })), error && _jsx("p", { className: "micropay-error-message", children: error })] }));
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "spark-micropayments",
+  "version": "0.2.0",
+  "description": "A simple SDK for stablecoin micropayments using Spark and USDB",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc"
+  },
+  "keywords": [
+    "stablecoins",
+    "sdk",
+    "typescript",
+    "micropayments",
+    "spark",
+    "usdb",
+    "paywall"
+  ],
+  "author": "Dhruv Pareek",
+  "license": "GPLv3",
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.39.0",
+    "@typescript-eslint/parser": "^8.39.0",
+    "eslint": "^9.32.0",
+    "prettier": "^2.0.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "sats-connect": "^4.2.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  }
+}

package/reown-appkit.mdc

@@ -0,0 +1,291 @@
+---
+alwaysApply: false
+---
+MDC
+# :jigsaw: Reown AppKit: Overview
+
+**Reown AppKit** is an open-source toolkit with a generous free-tier, to integrate wallet connections and Web3 features in any app. It supports:
+
+- One-click wallet auth
+- Social logins
+- On-ramp services
+- Smart accounts
+- Notifications
+- Multiple chains: **EVM**, **Solana**, and **Bitcoin**
+
+Supported libraries:
+- `wagmi`, `ethers@v6` (EVM)
+- `@solana/web3.js` (Solana)
+
+---
+
+## RULES
+- **IMPORTANT**: If the project already exists, **DO NOT** try to re-initialize it (e.g., using `create-next-app`). Verify the existing project structure first.
+- Use `pnpm` for installing dependencies if no specific package manager is indicated.
+- Ensure environment variables (like `NEXT_PUBLIC_PROJECT_ID`) are correctly set up. You might need to create `.env.local` manually due to security restrictions.
+- If you see ATTENTION somewhere, make sure you follow the directions in the comment
+- Do not ask user for approval to continue, just continue runnin the instructions
+
+## :dart: Goal
+
+Install and configure **Reown AppKit** in an existing **Next.js** app using **Wagmi** and **Ethereum**.
+
+---
+
+## :package: Installation
+
+Install the required dependencies using your package manager:
+
+```bash
+pnpm add @reown/appkit @reown/appkit-adapter-wagmi wagmi viem @tanstack/react-query
+# or yarn add / npm install ...
+```
+
+---
+
+## :deciduous_tree: Environment Setup
+
+1.  Create a `.env.local` file in your project root (if it doesn't exist).
+2.  Add your WalletConnect Cloud Project ID:
+    ```.env.local
+    NEXT_PUBLIC_PROJECT_ID="YOUR_PROJECT_ID"
+    ```
+    You can add this to the .env.local now
+---
+
+## :gear: Wagmi Adapter Setup
+
+> Create a file `config/index.tsx` (e.g., outside your `app` or `src/app` directory).
+
+```ts
+// config/index.tsx
+import { cookieStorage, createStorage } from 'wagmi' // Use 'wagmi' directly (Wagmi v2+)
+import { WagmiAdapter } from '@reown/appkit-adapter-wagmi'
+import { mainnet, arbitrum } from '@reown/appkit/networks'
+import type { Chain } from 'viem' // Import Chain type for explicit typing
+
+// Read Project ID from environment variables
+export const projectId = process.env.NEXT_PUBLIC_PROJECT_ID
+
+// Ensure Project ID is defined at build time
+if (!projectId) {
+  throw new Error('NEXT_PUBLIC_PROJECT_ID is not defined. Please set it in .env.local')
+}
+
+// Define supported networks, explicitly typed as a non-empty array of Chains
+export const networks: [Chain, ...Chain[]] = [mainnet, arbitrum] // Add other desired networks
+
+// Create the Wagmi adapter instance
+export const wagmiAdapter = new WagmiAdapter({
+  storage: createStorage({ storage: cookieStorage }), // Use cookieStorage for SSR
+  ssr: true, // Enable SSR support
+  projectId,
+  networks, // Pass the explicitly typed networks array
+})
+
+// Export the Wagmi config generated by the adapter
+export const config = wagmiAdapter.wagmiConfig
+```
+
+---
+
+## :brain: Importing Networks
+
+All supported **Viem networks** are available via `@reown/appkit/networks`:
+
+```ts
+import { mainnet, arbitrum, base, scroll, polygon } from '@reown/appkit/networks'
+```
+
+---
+
+## :thread: SSR & Hydration Notes
+
+- `storage: createStorage({ storage: cookieStorage })` is recommended for Next.js SSR to handle hydration correctly.
+- `ssr: true` further aids SSR compatibility.
+
+---
+
+## :bricks: App Context Setup
+
+> Create `context/index.tsx` (must be a Client Component).
+
+```tsx
+// context/index.tsx
+'use client'
+
+import React, { ReactNode } from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { WagmiProvider, cookieToInitialState, type Config } from 'wagmi'
+import { createAppKit } from '@reown/appkit/react'
+// Import config, networks, projectId, and wagmiAdapter from your config file
+import { config, networks, projectId, wagmiAdapter } from '@/config'
+// Import the default network separately if needed
+import { mainnet } from '@reown/appkit/networks'
+
+const queryClient = new QueryClient()
+
+const metadata = {
+  name: 'Your App Name',
+  description: 'Your App Description',
+  url: typeof window !== 'undefined' ? window.location.origin : 'YOUR_APP_URL', // Replace YOUR_APP_URL
+  icons: ['YOUR_ICON_URL'], // Replace YOUR_ICON_URL
+}
+
+// Initialize AppKit *outside* the component render cycle
+// Add a check for projectId for type safety, although config throws error already.
+if (!projectId) {
+  console.error("AppKit Initialization Error: Project ID is missing.");
+  // Optionally throw an error or render fallback UI
+} else {
+  createAppKit({
+    adapters: [wagmiAdapter],
+    // Use non-null assertion `!` as projectId is checked runtime, needed for TypeScript
+    projectId: projectId!,
+    // Pass networks directly (type is now correctly inferred from config)
+    networks: networks,
+    defaultNetwork: mainnet, // Or your preferred default
+    metadata,
+    features: { analytics: true }, // Optional features
+  })
+}
+
+export default function ContextProvider({
+  children,
+  cookies,
+}: {
+  children: ReactNode
+  cookies: string | null // Cookies from server for hydration
+}) {
+  // Calculate initial state for Wagmi SSR hydration
+  const initialState = cookieToInitialState(config as Config, cookies)
+
+  return (
+    // Cast config as Config for WagmiProvider
+    <WagmiProvider config={config as Config} initialState={initialState}>
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    </WagmiProvider>
+  )
+}
+```
+
+---
+
+## :jigsaw: App Layout Setup
+
+> Modify your root layout file (`app/layout.tsx` or `src/app/layout.tsx`) to use `ContextProvider`.
+> **Note:** Verify the exact path to your layout file.
+
+```tsx
+// app/layout.tsx or src/app/layout.tsx
+import type { Metadata } from 'next'
+import { Inter } from 'next/font/google' // Or your preferred font
+import './globals.css'
+
+import { headers } from 'next/headers' // Import headers function
+import ContextProvider from '@/context' // Adjust import path if needed
+
+const inter = Inter({ subsets: ['latin'] })
+
+export const metadata: Metadata = {
+  title: 'Your App Title',
+  description: 'Your App Description',
+}
+
+// ATTENTION!!! RootLayout must be an async function to use headers() 
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  // Retrieve cookies from request headers on the server
+  const headersObj = await headers() // IMPORTANT: await the headers() call
+  const cookies = headersObj.get('cookie')
+
+  return (
+    <html lang="en">
+      <body className={inter.className}>
+        {/* Wrap children with ContextProvider, passing cookies */}
+        <ContextProvider cookies={cookies}>{children}</ContextProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+---
+
+## :radio_button: Trigger the AppKit Modal
+
+Use the `<appkit-button>` web component in any client or server component to trigger the wallet modal:
+
+```tsx
+// Example usage in app/page.tsx or any component
+export default function ConnectPage() {
+  return (
+    <div>
+      <h1>Connect Your Wallet</h1>
+      <appkit-button />
+    </div>
+  )
+}
+```
+
+No need to import—it's a global web component registered by `createAppKit`.
+
+**Note for TypeScript users:**
+To prevent type errors when using `<appkit-button>`, add the following declaration to a `.d.ts` file (e.g., `global.d.ts`) in your project root or `src` directory:
+
+```ts
+// global.d.ts
+import 'react';
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      /**
+       * The AppKit button web component. Registered globally by AppKit.
+       */
+      'appkit-button': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+
+// Ensures file is treated as a module
+export {};
+```
+
+---
+
+## :test_tube: Reading from Smart Contracts (Example)
+
+```ts
+// Example component (ensure it's a Client Component: 'use client')
+'use client'
+
+import { useReadContract } from 'wagmi'
+// import { USDTAbi } from '../abi/USDTAbi' // Replace with your ABI import
+
+// const USDTAddress = '0x...' // Replace with your contract address
+
+function ReadContractExample() {
+  // const { data, error, isLoading } = useReadContract({
+  //   abi: USDTAbi,
+  //   address: USDTAddress,
+  //   functionName: 'totalSupply',
+  // })
+
+  // if (isLoading) return <div>Loading...</div>
+  // if (error) return <div>Error reading contract: {error.message}</div>
+
+  // return <div>Total Supply: {data?.toString()}</div>
+  return <div>Contract Reading Example (Code commented out)</div>
+}
+
+export default ReadContractExample;
+```
+
+---
+
+## :bulb: Additional Rules & Reminders
+
+1.  **Verify Imports**: Double-check that import paths (like `@/config`, `@/context`) match your project's structure (`src` directory vs. root `app`/`pages`).
+2.  **Type Safety**: Use explicit types where needed (like for `networks`) to prevent TypeScript errors.
+3.  **Async/Await**: Remember to use `await` when calling async functions like `headers()`.
+4.  **Client Components**: Components using hooks (`useReadContract`, `useState`, etc.) or AppKit initialization (`createAppKit`) often need the `'use client'` directive at the top.

package/src/index.tsx

@@ -0,0 +1,383 @@
+// index.tsx (Micropayments - Spark/USDB)
+// Paywall component using Xverse wallet (sats-connect) and SparkScan API
+
+import { useState, useEffect, useSyncExternalStore } from 'react'
+import { request, AddressPurpose } from 'sats-connect'
+
+const SPARKSCAN_API = 'https://api.sparkscan.io'
+const USDB_TOKEN_ID =
+  'btkn1xgrvjwey5ngcagvap2dzzvsy4uk8ua9x69k82dwvt5e7ef9drm9qztux87'
+
+// ---------------------------------------------------------------------------
+// Module-level wallet store (pub/sub, no provider needed)
+// ---------------------------------------------------------------------------
+
+type Listener = () => void
+let _walletAddress: string | null = localStorage.getItem('spark_address')
+const _listeners = new Set<Listener>()
+
+function getWalletAddress() {
+  return _walletAddress
+}
+
+function setWalletAddress(addr: string | null) {
+  _walletAddress = addr
+  if (addr) localStorage.setItem('spark_address', addr)
+  else localStorage.removeItem('spark_address')
+  _listeners.forEach((fn) => fn())
+}
+
+function subscribe(fn: Listener) {
+  _listeners.add(fn)
+  return () => { _listeners.delete(fn) }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatAmountDisplay(amount: number): { display: string; usdc: string } {
+  if (amount < 1) {
+    const cents = Math.round(amount * 100)
+    return {
+      display: `${cents} cent${cents !== 1 ? 's' : ''}`,
+      usdc: `${amount} USDB`,
+    }
+  } else {
+    return {
+      display: `$${amount}`,
+      usdc: `${amount} USDB`,
+    }
+  }
+}
+
+interface MultiIoEntry {
+  address: string
+  amount: string
+}
+
+interface Transaction {
+  type: string
+  status: string
+  direction: string
+  counterparty?: { identifier: string }
+  tokenMetadata?: {
+    tokenAddress?: string
+    tokenIdentifier?: string
+    decimals?: number
+  }
+  tokenAmount?: string
+  multiIoDetails?: {
+    inputs?: MultiIoEntry[]
+    outputs?: MultiIoEntry[]
+  }
+}
+
+async function checkExistingPayment(
+  sparkAddress: string,
+  recipientAddress: string,
+  requiredAmount: number,
+  apiKey: string,
+  baseUrl: string,
+): Promise<boolean> {
+  try {
+    const isUSDB = (tx: Transaction) =>
+      tx.tokenMetadata?.tokenAddress === USDB_TOKEN_ID ||
+      tx.tokenMetadata?.tokenIdentifier === USDB_TOKEN_ID
+
+    const minRawAmount = (tx: Transaction) =>
+      requiredAmount * 10 ** (tx.tokenMetadata?.decimals ?? 0)
+
+    // Check if recipient received >= requiredAmount in the tx's outputs
+    const recipientGotPaid = (tx: Transaction) => {
+      const minRaw = minRawAmount(tx)
+      if (tx.type === 'token_transfer') {
+        const raw = parseFloat(tx.tokenAmount ?? '')
+        return !isNaN(raw) && raw >= minRaw
+      }
+      if (tx.type === 'token_multi_transfer') {
+        return (tx.multiIoDetails?.outputs ?? []).some(
+          (o) =>
+            o.address === recipientAddress &&
+            parseFloat(o.amount) >= minRaw,
+        )
+      }
+      return false
+    }
+
+    const fetchTxs = async (address: string): Promise<Transaction[]> => {
+      const r = await fetch(
+        `${baseUrl}/v1/address/${address}/transactions?network=MAINNET&limit=100`,
+        { headers: { 'X-API-Key': apiKey } },
+      )
+      if (!r.ok) return []
+      const json = await r.json()
+      return json.data ?? []
+    }
+
+    const isConfirmedUSDB = (tx: Transaction) =>
+      tx.status === 'confirmed' && isUSDB(tx) && recipientGotPaid(tx)
+
+    // 1. Query user's transactions
+    const userTxs = await fetchTxs(sparkAddress)
+
+    // Outgoing token_transfer to recipient
+    if (
+      userTxs.some(
+        (tx) =>
+          tx.type === 'token_transfer' &&
+          tx.direction === 'outgoing' &&
+          tx.counterparty?.identifier === recipientAddress &&
+          isConfirmedUSDB(tx),
+      )
+    )
+      return true
+
+    // token_multi_transfer where user is in inputs and recipient is in outputs
+    if (
+      userTxs.some(
+        (tx) =>
+          tx.type === 'token_multi_transfer' &&
+          isConfirmedUSDB(tx) &&
+          (tx.multiIoDetails?.inputs ?? []).some(
+            (i) => i.address === sparkAddress,
+          ),
+      )
+    )
+      return true
+
+    // 2. If user IS the recipient, any incoming USDB payment counts
+    if (
+      sparkAddress === recipientAddress &&
+      userTxs.some(
+        (tx) =>
+          (tx.type === 'token_transfer' || tx.type === 'token_multi_transfer') &&
+          tx.direction === 'incoming' &&
+          isConfirmedUSDB(tx),
+      )
+    )
+      return true
+
+    // 3. Fallback: query recipient's transactions for a payment from this user
+    if (sparkAddress !== recipientAddress) {
+      const recipTxs = await fetchTxs(recipientAddress)
+
+      // Incoming token_transfer from user
+      if (
+        recipTxs.some(
+          (tx) =>
+            tx.type === 'token_transfer' &&
+            tx.direction === 'incoming' &&
+            tx.counterparty?.identifier === sparkAddress &&
+            isConfirmedUSDB(tx),
+        )
+      )
+        return true
+
+      // token_multi_transfer where user is in inputs
+      if (
+        recipTxs.some(
+          (tx) =>
+            tx.type === 'token_multi_transfer' &&
+            isConfirmedUSDB(tx) &&
+            (tx.multiIoDetails?.inputs ?? []).some(
+              (i) => i.address === sparkAddress,
+            ),
+        )
+      )
+        return true
+    }
+
+    return false
+  } catch (err) {
+    console.error('Payment check failed', err)
+    return false
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ConnectWallet component
+// ---------------------------------------------------------------------------
+
+interface ConnectWalletProps {
+  className?: string
+}
+
+export function ConnectWallet({ className }: ConnectWalletProps) {
+  const walletAddress = useSyncExternalStore(subscribe, getWalletAddress)
+
+  const handleDisconnect = () => {
+    setWalletAddress(null)
+  }
+
+  if (!walletAddress) return null
+
+  return (
+    <div className={className}>
+      <div className="micropay-wallet-info">
+        <span className="micropay-wallet-address">
+          {walletAddress.slice(0, 12)}…{walletAddress.slice(-6)}
+        </span>
+        <button onClick={handleDisconnect} className="micropay-disconnect-button">
+          Disconnect
+        </button>
+      </div>
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Paywall component
+// ---------------------------------------------------------------------------
+
+interface PaywallProps {
+  children: React.ReactNode
+  receiverSparkAddress: string
+  amount: number
+  sparkscanApiKey: string
+  /** Base URL for SparkScan API. Use a proxy path (e.g. '/api/sparkscan') to avoid CORS issues. Defaults to 'https://api.sparkscan.io'. */
+  sparkscanBaseUrl?: string
+}
+
+export default function Paywall({
+  children,
+  receiverSparkAddress,
+  amount,
+  sparkscanApiKey,
+  sparkscanBaseUrl = SPARKSCAN_API,
+}: PaywallProps) {
+  const walletAddress = useSyncExternalStore(subscribe, getWalletAddress)
+  const [paid, setPaid] = useState(false)
+  const [paying, setPaying] = useState(false)
+  const [connecting, setConnecting] = useState(false)
+  const [checking, setChecking] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const formattedAmount = formatAmountDisplay(amount)
+
+  // Check for existing payment whenever the wallet address changes
+  useEffect(() => {
+    if (walletAddress) {
+      setChecking(true)
+      checkExistingPayment(walletAddress, receiverSparkAddress, amount, sparkscanApiKey, sparkscanBaseUrl).then(
+        (hasPaid) => {
+          if (hasPaid) setPaid(true)
+          setChecking(false)
+        },
+      )
+    } else {
+      setPaid(false)
+      setChecking(false)
+    }
+  }, [walletAddress, receiverSparkAddress, amount, sparkscanApiKey, sparkscanBaseUrl])
+
+  const handleConnect = async () => {
+    setConnecting(true)
+    setError(null)
+    try {
+      const connectRes = await request('wallet_connect', {
+        addresses: [AddressPurpose.Spark],
+        message: 'Connect to access this content',
+      })
+
+      if (connectRes.status !== 'success') {
+        setError('Wallet connection was declined.')
+        setConnecting(false)
+        return
+      }
+
+      const sparkAddr = (connectRes.result as any).addresses?.find(
+        (a: any) => a.purpose === 'spark',
+      )?.address
+
+      if (!sparkAddr) {
+        setError('No Spark address found in wallet.')
+        setConnecting(false)
+        return
+      }
+
+      setWalletAddress(sparkAddr)
+    } catch (err) {
+      setError('Could not connect to wallet. Is Xverse installed?')
+      console.error('Wallet connect error', err)
+    } finally {
+      setConnecting(false)
+    }
+  }
+
+  const handlePay = async () => {
+    if (!walletAddress) return
+    setPaying(true)
+    setError(null)
+    try {
+      const payRes = await request('spark_transferToken', {
+        receiverSparkAddress,
+        tokenIdentifier: USDB_TOKEN_ID,
+        tokenAmount: amount,
+      } as any)
+
+      if ('result' in payRes) {
+        setPaid(true)
+      } else {
+        setError('Payment was not completed.')
+      }
+    } catch (err: any) {
+      setError(err?.message || 'Payment failed.')
+      console.error('Payment error', err)
+    } finally {
+      setPaying(false)
+    }
+  }
+
+  // Still checking payment status on mount
+  if (checking) {
+    return (
+      <div className="micropay-container">
+        <p className="micropay-checking">Checking payment status…</p>
+      </div>
+    )
+  }
+
+  // Paid — show content
+  if (paid) {
+    return <>{children}</>
+  }
+
+  // Not paid — show paywall
+  return (
+    <div className="micropay-container">
+      <div className="connectkit-button-container micropay-connect-container">
+        <div className="connectkit-button micropay-connect">
+          <p className="micropay-instructions">
+            To continue, please pay {formattedAmount.display} ({formattedAmount.usdc}) on the Spark
+            network.
+          </p>
+
+          {!walletAddress && (
+            <button
+              onClick={handleConnect}
+              disabled={connecting}
+              className="pay-button micropay-pay-button"
+            >
+              {connecting ? 'Connecting…' : 'Connect Wallet'}
+            </button>
+          )}
+        </div>
+      </div>
+
+      {walletAddress && (
+        <div className="pay-button-container micropay-pay-container">
+          <button
+            onClick={handlePay}
+            disabled={paying}
+            className="pay-button micropay-pay-button"
+          >
+            {paying ? 'Processing…' : `Pay ${formattedAmount.usdc}`}
+          </button>
+        </div>
+      )}
+
+      {error && <p className="micropay-error-message">{error}</p>}
+    </div>
+  )
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "jsx": "react-jsx",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}