h402-FastSet Integration

This is an integration for h402 with the Pi2 FastSet Network.

The h402 protocol enables blockchain-agnostic payments for protected content, and this integration extends support to FastSet alongside existing EVM and Solana networks.

This integration provides a complete proof-of-concept for FastSet payments within the h402 protocol. The implementation includes client-side wallet integration, payment UI components, basic facilitator structure, and configuration management. The system successfully demonstrates end-to-end FastSet payment flow from wallet connection through payment completion.

System Overview

The integration works through several interconnected components that collectively enable FastSet payments within the h402 protocol framework:

• Technical Architecture: The system extends the existing h402 multi-blockchain architecture through a discriminated union type system that provides compile-time safety and runtime validation for FastSet payments. The core integration leverages TypeScript's type system to define FastSet-specific interfaces (FastSetAccountInfo, FastSetWallet, FastSetPaymentPayload) that seamlessly integrate with the existing EVM and Solana type definitions, ensuring type safety from wallet interaction through facilitator verification.

• Payment Flow Infrastructure: The implementation follows a layered architecture where React context providers manage wallet state, payment handler components orchestrate transaction flows, and h402 clients translate between FastSet wallet extension APIs and protocol-compliant payment headers. The system uses a provider pattern for wallet integration (FastSetWalletContext) that mirrors existing blockchain implementations, enabling consistent behavior across all supported networks while handling FastSet-specific connection management, account detection, and transaction signing.

• Protocol Integration: At the protocol level, the system extends the h402 exact payment scheme to support FastSet payment headers through client-side payment creation (fastset/client.ts) and server-side facilitator verification. The middleware automatically detects FastSet payment requirements and activates the appropriate payment flow, while the facilitator infrastructure provides a framework for transaction verification against FastSet. The configuration system uses environment-based payment requirements that define token addresses, amounts, recipient addresses, and network parameters, enabling flexible deployment across different environments.

• End-to-End Flow: The complete payment process begins when users encounter h402-protected content with FastSet payment requirements. The system automatically renders FastSet as a payment option, manages wallet extension detection and connection, handles transaction creation and signing through the FastSet wallet API, generates h402-compliant payment headers, submits payments for facilitator verification, and grants content access upon successful payment validation. This flow maintains consistency with existing blockchain implementations while accommodating FastSet-specific transaction formats and wallet interaction patterns.

Getting Started with FastSet Demo

Get up and running with the FastSet h402 integration in minutes.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher)
• pnpm: Install globally with npm install -g pnpm
• FastSet Wallet Extension: Required for FastSet payment interactions

Step 1: Install Dependencies

Install all project dependencies using pnpm:

pnpm install

Step 2: Configure and Start the Facilitator

The facilitator handles payment verification for the h402 protocol.

Navigate to facilitator directory:

cd typescript/packages/facilitator

Copy the environment template, edit the .env file, and set your EVM_PRIVATE_KEY

cp example.env .env

Go back to the root directory:

cd ../../..

Step 3: Configure the Example Application

Set up the Next.js example app with proper a facilitator connection.

Navigate to the example app:

cd examples/typescript/fullstack/next

Copy and edit your env file to be able to generate pictures:

cp example.env .env.local

Return to project root:

cd ../../../..

Note: In case you want to modify the address you pay to, change the file in examples/typescript/fullstack/next/config/paymentRequirements.ts:

export const fastsetNativePaymentRequirements: PaymentRequirements = {
    namespace: "fastset",
    tokenAddress: "0xfa575e7000000000000000000000000000000000000000000000000000000000", // Native SET token
    amountRequired: 100, // 100 SET tokens
    amountRequiredFormat: "humanReadable", // Human readable format
    payToAddress: ,
    networkId: "devnet", // FastSet devnet
    description: "Generate AI image with FastSet",
    resource: "https://example.com/resource",
    scheme: "exact",
    mimeType: "application/json",
    outputSchema: null,
    estimatedProcessingTime: 30,
    extra: null,
    maxAmountRequired: undefined,
    requiredDeadlineSeconds: undefined,
    tokenDecimals: 0,
    tokenSymbol: "SET",
    };

Step 4: Build and Launch

Build all packages and start the demo application.

Create the paywall directory structure:

mkdir -p ./typescript/packages/h402/src/shared/paywall

Generate a mock paywall component

echo 'export const paywallHtml = "<html><head><title>Mock Paywall</title></head><body><div>Payment Required</div></body></html>";' > ./typescript/packages/h402/src/shared/paywall/paywallHtml.ts

Make the build script executable and run it:

chmod +x ./scripts/build-all-and-start-example.sh

Start the demo app:

./scripts/build-all-and-start-example.sh

While the script is building the project, go to another terminal and run the facilitator:

cd typescript/packages/facilitator

Copy the environment template, edit the .env file, and set your EVM_PRIVATE_KEY

cp example.env .env

Start the facilitator server:

pnpm dev

Note 1: The script above also builds the facilitator, so check that it is running the demo before starting the facilitator.

Note 2: Keep this terminal running as the facilitator needs to stay active.

Step 5: Set Up FastSet Wallet

Open your Chrome, Brave, or Edge browser and install the FastSet Wallet Extension

Step 6: Try out the payment workflow

Open the Protected Route:

• Navigate to http://localhost:3000/ in your browser
• You should see a prompt field for image generation.
• Add random image description, like, "a cat".
• Then press the button.

Connect Your Wallet:

• Check that your browser wallet is active.
• Select the Fastset network and Set coin in the new payment form.
• Press the Pay button and approve the payment request in your FastSet wallet extension.

Access Protected Content:

• The image generation should start shortly after the payment.
• After successful generation, you should see your image.

Implementation Details

In order to add FastSet support, we added the following:

1. Add FastSet Types and Schemas

The type system forms the foundation of FastSet integration by providing compile-time safety and runtime validation. These types define the interface between the FastSet wallet extension, the h402 protocol, and the application layer. The discriminated union approach ensures that FastSet payments are handled correctly throughout the system while maintaining compatibility with existing EVM and Solana payment types.

The schema definitions enable automatic validation of FastSet payment payloads, ensuring that malformed or incompatible payments are rejected early in the process. This type of safety extends from the wallet interaction layer through to the facilitator verification process.

Files modified:

• Core FastSet types in typescript/packages/h402/src/types/shared/fastset.ts: Defines FastSetAccountInfo, FastSetTransactionCertificate, FastSetTransferParams, and FastSetWallet interfaces that represent the FastSet wallet extension API
• Payment payload types in typescript/packages/h402/src/types/verify/fastsetPayload.ts: Defines FastSetPaymentPayload structure for h402 protocol compatibility
• Network type extensions in typescript/packages/h402/src/types/shared/network.ts: Adds FastSet as a supported network type with discriminated unions for type safety
• Client type extensions in typescript/packages/h402/src/types/shared/client.ts: Extends payment client interfaces to support FastSet wallet integration
• h402 specification updates in typescript/packages/h402/src/types/verify/h402Specs.ts: Updates discriminated union schemas to include FastSet payment payloads

2. Add FastSet Wallet Context

The FastSet wallet context serves as the bridge between the FastSet browser extension and the React application. This context manages the complete lifecycle of wallet interaction, from initial detection and connection through account management and transaction signing. It follows the same patterns established for EVM and Solana wallet contexts, ensuring consistent behavior across all supported blockchain networks.

The context handles wallet state management, connection persistence, error handling, and provides a clean API for components to interact with the FastSet wallet without directly interfacing with the browser extension. This abstraction allows for easier testing and potential future migration to different wallet connection methods.

Files modified:

• FastSetWalletContext in typescript/packages/h402/src/paywall-app/src/fastset/context/FastSetWalletContext.tsx: React context provider that manages FastSet wallet connection, account state, and wallet detection

3. Add FastSet Payment React Component

The FastSet payment components integrate into the existing paywall system to provide a seamless payment experience. The main FastSetPaymentHandler component orchestrates the entire payment flow, from wallet connection through transaction completion. It integrates with the wallet context to manage connection state and provides user feedback throughout the payment process.

The component follows the same interface pattern as existing EVM and Solana payment handlers, ensuring consistent behavior and user experience across all supported networks. Integration into the main paywall component enables automatic detection and rendering of FastSet payment options based on the configured payment requirements.

Files modified:

• FastSetPaymentHandler in typescript/packages/h402/src/paywall-app/src/fastset/components/FastSetPaymentHandler.tsx: React component that handles FastSet payment flow, including wallet connection, payment processing, and transaction signing
• App.tsx integration in typescript/packages/h402/src/paywall-app/src/App.tsx: Adds FastSetWalletProvider to the application provider hierarchy
• Paywall integration in typescript/packages/h402/src/paywall-app/src/components/Paywall.tsx: Updates main paywall component to detect and render FastSet payment options when FastSet payment requirements are present

4. Add FastSet Client Integration

The client integration provides the core functionality for creating h402-compliant payment headers using FastSet wallets. This implementation handles the translation between FastSet wallet extension APIs and the h402 protocol requirements. The client manages transaction creation, signing, and formatting to ensure compatibility with the h402 payment verification process.

The integration extends the existing h402 client architecture to support FastSet alongside EVM and Solana clients. The payment header creation process maintains the same interface while handling FastSet-specific transaction formats and wallet interaction patterns.

Files modified:

• FastSet payment client in typescript/packages/h402/src/schemes/exact/fastset/client.ts: Core client implementation that interfaces with FastSet wallet extension to create payment transactions
• Payment header creation: Updates in typescript/packages/h402/src/client/createPaymentHeader.ts to support FastSet payment clients
• Scheme integration: Updates in typescript/packages/h402/src/schemes/exact/index.ts to include FastSet in the exact payment scheme
• Utility functions in typescript/packages/h402/src/schemes/exact/fastset/utils/paymentUtils.ts: Helper functions for FastSet payment processing
• Package exports: Updated main export files to expose FastSet functionality

5. Add Facilitator for FastSet

The facilitator integration provides server-side infrastructure for FastSet payment verification and settlement, following the same architectural patterns as existing EVM and Solana facilitators.

Key Features:

• Network Integration: Direct RPC calls to FastSet staging network (https://staging.proxy.fastset.xyz/) using set_proxy_getAccountInfo method
• Transaction Verification: Validates transaction nonce, sender/recipient addresses, and transfer amounts against network state
• Simple Settlement: Transactions are settled in the wallet, so the settle function acts as a pass-through after verification

Files implemented:

• FastSet facilitator core in typescript/packages/h402/src/facilitator/fastset/facilitator.ts: Main facilitator routing for FastSet namespace
• Exact scheme implementation in typescript/packages/h402/src/schemes/exact/fastset/facilitator.ts: Complete verification and settlement logic with RPC integration
• Core facilitator integration in typescript/packages/h402/src/facilitator/index.ts: Routes FastSet payments to appropriate handlers

The implementation is ready for staging/testing use with the FastSet staging network and requires the bech32 library dependency.

6. Configuration and Requirements

The configuration system enables FastSet payments by defining payment requirements and connecting the various system components. Payment requirements specify the exact parameters for FastSet transactions, including token addresses, amounts, recipient addresses, and network identification. These requirements are automatically detected by the middleware and passed through to the paywall system.

The middleware integration enables automatic FastSet payment flow activation when FastSet payment requirements are present. The system uses environment variables to configure facilitator endpoints, enabling flexible deployment across development, testing, and production environments.

Files modified:

• Payment requirements configuration in examples/typescript/fullstack/next/config/paymentRequirements.ts: Added fastsetNativePaymentRequirements configuration that defines FastSet payment parameters, including token address, amount, recipient address, and network identification
• Middleware integration: The Next.js middleware automatically detects FastSet payment requirements and enables the FastSet payment flow when configured

Setup Requirements: To test the integration, you need to spawn a custom facilitator that supports FastSet verification. The system uses the FACILITATOR_URL environment variable to point to the local facilitator instance for development and testing.