Astra SDK

English | 简体中文

English Documentation

Astra 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 Astra SDK
    participant L as LSP Node
    participant E as EVM Chain
    
    U->>S: astraSend(amount, assetId)
    S->>L: Request Quote & Astra 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 Astra SDK
    participant E as EVM Chain
    participant L as LSP Node
    
    U->>S: astraReceive(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

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

npm install @lnfi-network/astra-sdk wagmi viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query

Basic Usage

import React from 'react';
import { AstraProvider, AstraModal, astraSend, astraReceive } from '@lnfi-network/astra-sdk';

function App() {
  return (
    <AstraProvider 
      projectId="YOUR_WALLET_CONNECT_PROJECT_ID" 
      env="production" // 'production' or 'development'
    >
      <AstraModal />
      
      {/* Lightning to EVM */}
      <button onClick={() => astraSend({
        assetId: "your-asset-id",
        amount: 1000,
        waitConfirm: true,
        onAstraInvoice: (invoice, tx, txUrl) => {
          console.log("Astra Invoice Generated:", invoice);
        }
      })}>
        Bridge from Lightning
      </button>
      
      {/* EVM to Lightning */}
      <button onClick={() => astraReceive({
        assetId: "your-asset-id",
        invoice: "lnbc..." // Your receiving lightning invoice
      })}>
        Bridge to Lightning
      </button>
    </AstraProvider>
  );
}

📖 API Reference

AstraProvider

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

astraSend

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) | | onAstraInvoice | function | Callback: (invoice, tx, txUrl) => void |

astraReceive

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 |

中文文档

Astra SDK 是一个强大的 React 库，旨在实现 EVM 兼容区块链与比特币闪电网络（Lightning Network）之间的无缝资产跨链转换。

✨ 功能特性

• 跨链桥接：在 EVM 链和闪电网络之间进行资产转换。
• 多链支持：支持 Ethereum, Base, BSC, Botanix 测试网等。
• 钱包集成：内置对 WalletConnect 和主流 Web3 钱包的支持。
• 响应式设计：移动端优先的设计，适配各种屏幕尺寸。
• 实时状态：交易状态和余额的实时监控与更新。
• 隔离样式：使用 astra 样式前缀，避免与宿主项目样式冲突。

🔄 业务流程

1. 闪电网络 转 EVM (提现)

场景：用户支付闪电网络 Sats，在 EVM 链上接收对应的代币。

sequenceDiagram
    participant U as 用户 / 应用
    participant S as Astra SDK
    participant L as LSP 节点
    participant E as EVM 区块链
    
    U->>S: astraSend(金额, 资产ID)
    S->>L: 请求报价并生成 Astra 发票
    L-->>S: 返回生成的闪电网络发票
    S->>U: 引导用户使用钱包支付
    U->>L: 用户支付发票
    L->>E: 触发智能合约脚本
    E-->>U: 将代币转入用户 EVM 钱包

2. EVM 转 闪电网络 (充值)

场景：用户在 EVM 链上支付代币，接收闪电网络上的比特币。

sequenceDiagram
    participant U as 用户 / 应用
    participant S as Astra SDK
    participant E as EVM 区块链
    participant L as LSP 节点
    
    U->>S: astraReceive(发票, 资产ID)
    S-->>U: 显示转换详情及报价
    U->>E: 授权并调用合约进行支付
    E-->>L: 合约锁定资产
    L->>U: 向用户的闪电网络发票付款

🚀 快速上手

安装

Astra SDK 需要以下 peer dependencies 配合使用：

npm install @lnfi-network/astra-sdk wagmi viem @reown/appkit @reown/appkit-adapter-wagmi @tanstack/react-query

基础用法

import React from 'react';
import { AstraProvider, AstraModal, astraSend, astraReceive } from '@lnfi-network/astra-sdk';

function App() {
  return (
    <AstraProvider 
      projectId="YOUR_WALLET_CONNECT_PROJECT_ID" 
      env="production" // 'production' (正式网) 或 'development' (测试网)
    >
      <AstraModal />
      
      {/* 闪电网络 转 EVM (提现) */}
      <button onClick={() => astraSend({
        assetId: "your-asset-id",
        amount: 1000,
        onAstraInvoice: (invoice, tx, txUrl) => {
          console.log("生成的 Astra 发票:", invoice);
        }
      })}>
        从闪电网络桥接
      </button>
      
      {/* EVM 转 闪电网络 (充值) */}
      <button onClick={() => astraReceive({
        assetId: "your-asset-id",
        invoice: "lnbc..." // 你的闪电网络收款发票
      })}>
        桥接到闪电网络
      </button>
    </AstraProvider>
  );
}

📖 API 参考

AstraProvider (配置项)

| 属性 | 类型 | 默认值 | 描述 | | :--- | :--- | :--- | :--- | | projectId | string | 必填 | 从 cloud.reown.com 申请的 WalletConnect 项目 ID | | env | 'production' \| 'development' | 'production' | 运行环境。'development' 会切换到测试网（Sepolia, Base Sepolia） | | metadata | object | defaultMetadata | 在钱包中展示的应用信息（名称、描述、URL、图标） | | apiUrl | string | 自动配置 | 后端 API 地址。通常根据 env 自动切换 |

astraSend

从 闪电网络 (Lightning Network) 跨链到 EVM 链。

| 参数 | 类型 | 描述 | | :--- | :--- | :--- | | assetId | string | 资产 ID | | amount | number | 转换金额（单位：Sats） | | waitConfirm | boolean | 是否等待交易确认 (默认: true) | | onAstraInvoice | function | 回调函数: (invoice, tx, txUrl) => void |

astraReceive

从 EVM 链跨链到 闪电网络 (Lightning Network)。

| 参数 | 类型 | 描述 | | :--- | :--- | :--- | | assetId | string | 资产 ID | | invoice | string | 你用于接收资金的闪电网络发票 |

🛠️ 技术栈

• React 18 - UI 库
• Wagmi & Viem - 以太坊交互
• Reown AppKit - 钱包连接
• Ant Design - UI 组件 (使用 astra 前缀)
• Zustand - 状态管理

📄 许可证

MIT License - 详见 LICENSE 文件。

🔄 更新日志

v1.0.1

• 正式版发布
• 修复了包名识别问题
• 完善了环境变量配置（Support for env, apiUrl）
• 增加了 astraSend 回调函数的详细参数声明

Built with ❤️ by the Astra Labs team