NodeFlow SDK

NodeFlow SDK is a powerful React library that enables seamless asset bridging between EVM-compatible blockchains and the Bitcoin Lightning Network. Built with modern web technologies, it provides developers with an easy-to-integrate solution for cross-chain liquidity and payments.

✨ Features

• Cross-Chain Bridge: Bridge assets between EVM chains and Lightning Network.
• Multi-Chain Support: Support for Ethereum, Base, BSC, Botanix testnet, and more.
• Wallet Integration: Built-in support for WalletConnect and popular Web3 wallets.
• TypeScript Ready: Full TypeScript support with type definitions.
• Responsive Design: Mobile-first design with responsive UI components.
• Real-time Updates: Live transaction status and balance updates.
• Customizable Theme: Dark theme with customizable styling.

🔄 Workflows

1. Lightning to EVM (Withdraw)

Used when a user sends BTC via Lightning to receive tokens on an EVM chain.

sequenceDiagram
    participant U as User / App
    participant S as NodeFlow SDK
    participant L as LSP Node
    participant E as EVM Chain
    
    U->>S: nodeFlowSend(amount, assetId)
    S->>L: Request Quote & NodeFlow Invoice
    L-->>S: Return LN Invoice
    S->>U: Display Invoice to User
    U->>L: User pays via Lightning Wallet
    L->>E: Trigger Smart Contract Release
    E-->>U: Mint/Transfer Tokens to User

2. EVM to Lightning (Deposit)

Used when a user pays with EVM tokens to receive BTC on a Lightning Invoice.

sequenceDiagram
    participant U as User / App
    participant S as NodeFlow SDK
    participant E as EVM Chain
    participant L as LSP Node
    
    U->>S: nodeFlowReceive(invoice, assetId)
    S-->>U: Show detailed quote
    U->>E: Approve & Deposit Tokens
    E-->>L: Lock assets in Contract
    L->>U: Pay User's Lightning Invoice

🚀 Quick Start

Installation

NodeFlow SDK requires several peer dependencies to be installed in your project:

npm install nodeflow-sdk wagmi viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query

🧪 Testnet Environment Setup

To help you get started quickly on the Base Regtest testnet, use the following configuration:

| Item | Value | Description | | :--- | :--- | :--- | | Project ID | 92461524d3cfcb3d78b38b5dbd6a6ce3 | Public demo ID (please use your own for production) | | Env | "development" | Switches to Regtest / Base Sepolia | | Asset ID | f7ac99f2c068f1157c787012f50cb043437505c309c6d8685e135cd8481b1e9d | USDT (Taproot Asset) | | Token Address | 0x616F1207D8BbC71549b8AC41f4797df72EA39297 | USDT (Base Regtest) | | Invoice Generator | lnexchange | Generate Regtest invoices for testing |

Quick Start Example

Here is a copy-paste ready example for Regtest / Base Sepolia :

import React from 'react';
import { NodeFlowProvider, NodeFlowModal, nodeFlowSend, nodeFlowReceive } from 'nodeflow-sdk';

// Testnet Asset ID for USDT
const USDT_ASSET_ID = "f7ac99f2c068f1157c787012f50cb043437505c309c6d8685e135cd8481b1e9d";

function App() {
  return (
    <NodeFlowProvider 
      projectId="92461524d3cfcb3d78b38b5dbd6a6ce3" 
      env="development"
    >
      <NodeFlowModal />
      
      {/* 1. Lightning to EVM (Withdraw USDT) */}
      <button onClick={() => nodeFlowSend({
        assetId: USDT_ASSET_ID,
        amount: 10000,
        waitConfirm: true,
        onNodeFlowInvoice: (invoice, tx, txUrl) => {
          console.log("Pay this Invoice:", invoice);
        }
      })}>
        Get USDT on Base Sepolia
      </button>
      
      {/* 2. EVM to Lightning (Deposit USDT) */}
      <button onClick={() => nodeFlowReceive({
        assetId: USDT_ASSET_ID,
        invoice: "lnbcrt1..." // Get a test invoice from: https://devoflnexchange.unift.xyz/
      })}>
        Pay Lightning Invoice with USDT
      </button>
    </NodeFlowProvider>
  );
}

📖 API Reference

NodeFlowProvider

| Prop | Type | Default | Description | | :--- | :--- | :--- | | projectId | string | Required | WalletConnect project ID from cloud.reown.com | | env | 'production' \| 'development' | 'production' | Environment mode. 'development' uses testnets (Sepolia, Base Sepolia) | | metadata | object | defaultMetadata | App metadata for WalletConnect (name, description, url, icons) | | apiUrl | string | See note | Backend API URL. Automatically switches based on env | | adapter | WagmiAdapter | null | Optional custom Wagmi adapter if you want to reuse existing configuration |

nodeFlowSend

Bridge assets from Lightning Network to EVM chains.

| Parameter | Type | Description | | :--- | :--- | :--- | | assetId | string | The ID of the asset to bridge | | amount | number | Amount in satoshis | | waitConfirm | boolean | Whether to wait for transaction confirmation (default: true) | | onNodeFlowInvoice | function | Callback: (invoice, tx, txUrl) => void |

nodeFlowReceive

Bridge assets from EVM chains to Lightning Network.

| Parameter | Type | Description | | :--- | :--- | :--- | | assetId | string | The ID of the asset to bridge | | invoice | string | The Lightning Network invoice where you want to receive funds |

🛠️ Technical Stack

• React 18 - UI library
• Wagmi & Viem - Ethereum hooks & interface
• Reown AppKit - Wallet connection
• Ant Design - UI components (with nodeflow prefix)
• Zustand - State management

📄 License

MIT License - see LICENSE file for details.

🔄 Changelog

v1.0.1

• Renamed to nodeflow-sdk
• Rebranded API from Astra to NodeFlow
• Official release
• Added comprehensive environment configuration support
• Updated API callback signatures

Built with ❤️ by the NodeFlow Labs team