four-flap-meme-sdk 1.5.55 → 1.5.56

package/dist/sol/utils/transfer.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Solana SOL 转账功能
+ * SDK 只负责构建和签名交易，提交到后端服务器广播
+ * @module sol/utils/transfer
+ */
+import { Connection, Keypair, PublicKey, Transaction, TransactionInstruction } from '@solana/web3.js';
+/**
+ * 转账项
+ */
+export interface TransferItem {
+    to: string;
+    amount: bigint;
+}
+/**
+ * 签名后的转账交易
+ */
+export interface SignedTransferTransaction {
+    /** Base64 编码的交易数据 */
+    data: string;
+    /** 交易签名 */
+    signature: string;
+    /** 转账详情 */
+    transfers: TransferItem[];
+    /** blockhash */
+    recentBlockhash: string;
+    /** 最后有效区块高度 */
+    lastValidBlockHeight: number;
+}
+/**
+ * 批量签名结果
+ */
+export interface BatchSignedTransfers {
+    /** 签名后的交易列表 */
+    transactions: SignedTransferTransaction[];
+    /** 总转账数 */
+    totalTransfers: number;
+    /** 总交易数 */
+    totalTransactions: number;
+    /** 创建时间 */
+    createdAt: number;
+}
+/** 单笔交易最大转账数量（受 1232 bytes 限制） */
+export declare const MAX_TRANSFERS_PER_TX = 20;
+/**
+ * 构建转账指令
+ * @param from 发送者公钥
+ * @param to 接收者地址
+ * @param amount lamports
+ */
+export declare function buildTransferInstruction(from: PublicKey, to: string, amount: bigint): TransactionInstruction;
+/**
+ * 构建批量转账指令
+ * @param from 发送者公钥
+ * @param transfers 转账列表
+ */
+export declare function buildTransferInstructions(from: PublicKey, transfers: TransferItem[]): TransactionInstruction[];
+/**
+ * 指令组（用于批量转账分组）
+ */
+export interface InstructionGroup {
+    /** 该组的指令列表 */
+    instructions: TransactionInstruction[];
+    /** 该组的转账详情 */
+    transfers: TransferItem[];
+    /** 组索引 */
+    groupIndex: number;
+    /** 总组数 */
+    totalGroups: number;
+}
+/**
+ * 批量转账指令组结果
+ */
+export interface BatchTransferInstructionGroups {
+    /** 指令组列表 */
+    groups: InstructionGroup[];
+    /** 总转账数 */
+    totalTransfers: number;
+    /** 总组数 */
+    totalGroups: number;
+    /** 发送者公钥 */
+    from: PublicKey;
+}
+/**
+ * 构建批量转账指令组（支持超过 20 个地址，自动分组）
+ *
+ * 用于 SOL 分发场景：一个地址向多个地址转账
+ * 自动按 20 个一组分组，每组可以打包成一笔交易
+ *
+ * @param from 发送者公钥
+ * @param transfers 转账列表（可以超过 20 个）
+ * @param groupSize 每组大小（默认 20，最大 20）
+ * @returns 分组后的指令组
+ *
+ * @example
+ * // 100 个地址分发
+ * const groups = buildBatchTransferInstructionGroups(
+ *   wallet.publicKey,
+ *   distributions.map(d => ({ to: d.address, amount: BigInt(d.lamports) }))
+ * );
+ *
+ * // 返回 5 个组，每组 20 个转账指令
+ * console.log(groups.totalGroups); // 5
+ *
+ * // 每组可以单独构建交易
+ * for (const group of groups.groups) {
+ *   const tx = new Transaction();
+ *   group.instructions.forEach(ix => tx.add(ix));
+ *   // ... 签名并发送
+ * }
+ */
+export declare function buildBatchTransferInstructionGroups(from: PublicKey, transfers: TransferItem[], groupSize?: number): BatchTransferInstructionGroups;
+/**
+ * 从指令组构建交易（不签名）
+ * @param group 指令组
+ * @param blockhash 区块哈希
+ * @param feePayer 费用支付者
+ */
+export declare function buildTransactionFromGroup(group: InstructionGroup, blockhash: string, feePayer: PublicKey): Transaction;
+/**
+ * 从指令组构建并签名交易
+ * @param group 指令组
+ * @param blockhash 区块哈希
+ * @param signer 签名者
+ */
+export declare function buildAndSignTransactionFromGroup(group: InstructionGroup, blockhash: string, signer: Keypair): Transaction;
+/**
+ * 构建并签名单笔 SOL 转账
+ * @param connection Solana 连接
+ * @param from 发送者 Keypair
+ * @param to 接收者地址
+ * @param amount lamports
+ */
+export declare function signTransferSOL(connection: Connection, from: Keypair, to: string, amount: bigint): Promise<SignedTransferTransaction>;
+/**
+ * 构建并签名单笔 SOL 转账（使用 SOL 数量）
+ */
+export declare function signTransferSOLAmount(connection: Connection, from: Keypair, to: string, solAmount: number): Promise<SignedTransferTransaction>;
+/**
+ * 构建并签名批量转账（单笔交易，多个指令）
+ * 单笔交易最多约 20-30 个转账
+ * @param connection Solana 连接
+ * @param from 发送者 Keypair
+ * @param transfers 转账列表
+ */
+export declare function signBatchTransferSOL(connection: Connection, from: Keypair, transfers: TransferItem[]): Promise<SignedTransferTransaction>;
+/**
+ * 构建并签名批量转账（多笔交易）
+ * 自动分批处理大量转账
+ * @param connection Solana 连接
+ * @param from 发送者 Keypair
+ * @param transfers 转账列表
+ * @param batchSize 每批大小（默认 20）
+ */
+export declare function signBatchTransferSOLMultiple(connection: Connection, from: Keypair, transfers: TransferItem[], batchSize?: number): Promise<BatchSignedTransfers>;
+/**
+ * 多钱包转账项
+ */
+export interface MultiWalletTransferItem {
+    from: Keypair;
+    to: string;
+    amount: bigint;
+}
+/**
+ * 签名多钱包转账（每个钱包一笔交易）
+ * 用于归集或分发场景
+ * @param connection Solana 连接
+ * @param transfers 转账列表
+ */
+export declare function signMultiWalletTransfers(connection: Connection, transfers: MultiWalletTransferItem[]): Promise<BatchSignedTransfers>;
+/**
+ * 归集 SOL（多个钱包转到一个地址）
+ * @param connection Solana 连接
+ * @param wallets 钱包列表
+ * @param toAddress 目标地址
+ * @param amounts 每个钱包转账金额（lamports），如果为空则转全部（保留 5000 lamports 作为手续费）
+ */
+export declare function signCollectSOL(connection: Connection, wallets: Keypair[], toAddress: string, amounts?: bigint[]): Promise<BatchSignedTransfers>;
+/**
+ * 分发 SOL（一个钱包转到多个地址）
+ * @param connection Solana 连接
+ * @param from 发送者 Keypair
+ * @param distributions 分发列表
+ */
+export declare function signDistributeSOL(connection: Connection, from: Keypair, distributions: TransferItem[]): Promise<BatchSignedTransfers>;
+/**
+ * 将签名结果转换为后端 API 格式
+ */
+export declare function toBackendFormat(result: BatchSignedTransfers): {
+    transactions: Array<{
+        data: string;
+        signature: string;
+    }>;
+    totalTransfers: number;
+    totalTransactions: number;
+    timestamp: number;
+};

package/dist/sol/utils/transfer.js

@@ -0,0 +1,307 @@
+/**
+ * Solana SOL 转账功能
+ * SDK 只负责构建和签名交易，提交到后端服务器广播
+ * @module sol/utils/transfer
+ */
+import { PublicKey, SystemProgram, Transaction, } from '@solana/web3.js';
+import { solToLamports } from '../constants.js';
+// ==================== 常量 ====================
+/** 单笔交易最大转账数量（受 1232 bytes 限制） */
+export const MAX_TRANSFERS_PER_TX = 20;
+// ==================== 指令构建 ====================
+/**
+ * 构建转账指令
+ * @param from 发送者公钥
+ * @param to 接收者地址
+ * @param amount lamports
+ */
+export function buildTransferInstruction(from, to, amount) {
+    return SystemProgram.transfer({
+        fromPubkey: from,
+        toPubkey: new PublicKey(to),
+        lamports: amount,
+    });
+}
+/**
+ * 构建批量转账指令
+ * @param from 发送者公钥
+ * @param transfers 转账列表
+ */
+export function buildTransferInstructions(from, transfers) {
+    return transfers.map(t => buildTransferInstruction(from, t.to, t.amount));
+}
+/**
+ * 构建批量转账指令组（支持超过 20 个地址，自动分组）
+ *
+ * 用于 SOL 分发场景：一个地址向多个地址转账
+ * 自动按 20 个一组分组，每组可以打包成一笔交易
+ *
+ * @param from 发送者公钥
+ * @param transfers 转账列表（可以超过 20 个）
+ * @param groupSize 每组大小（默认 20，最大 20）
+ * @returns 分组后的指令组
+ *
+ * @example
+ * // 100 个地址分发
+ * const groups = buildBatchTransferInstructionGroups(
+ *   wallet.publicKey,
+ *   distributions.map(d => ({ to: d.address, amount: BigInt(d.lamports) }))
+ * );
+ *
+ * // 返回 5 个组，每组 20 个转账指令
+ * console.log(groups.totalGroups); // 5
+ *
+ * // 每组可以单独构建交易
+ * for (const group of groups.groups) {
+ *   const tx = new Transaction();
+ *   group.instructions.forEach(ix => tx.add(ix));
+ *   // ... 签名并发送
+ * }
+ */
+export function buildBatchTransferInstructionGroups(from, transfers, groupSize = MAX_TRANSFERS_PER_TX) {
+    if (transfers.length === 0) {
+        return {
+            groups: [],
+            totalTransfers: 0,
+            totalGroups: 0,
+            from,
+        };
+    }
+    // 确保 groupSize 不超过最大限制
+    const safeGroupSize = Math.min(groupSize, MAX_TRANSFERS_PER_TX);
+    // 计算总组数
+    const totalGroups = Math.ceil(transfers.length / safeGroupSize);
+    // 分组
+    const groups = [];
+    for (let i = 0; i < transfers.length; i += safeGroupSize) {
+        const batch = transfers.slice(i, i + safeGroupSize);
+        const groupIndex = Math.floor(i / safeGroupSize);
+        groups.push({
+            instructions: batch.map(t => buildTransferInstruction(from, t.to, t.amount)),
+            transfers: batch,
+            groupIndex,
+            totalGroups,
+        });
+    }
+    return {
+        groups,
+        totalTransfers: transfers.length,
+        totalGroups,
+        from,
+    };
+}
+/**
+ * 从指令组构建交易（不签名）
+ * @param group 指令组
+ * @param blockhash 区块哈希
+ * @param feePayer 费用支付者
+ */
+export function buildTransactionFromGroup(group, blockhash, feePayer) {
+    const tx = new Transaction();
+    group.instructions.forEach(ix => tx.add(ix));
+    tx.recentBlockhash = blockhash;
+    tx.feePayer = feePayer;
+    return tx;
+}
+/**
+ * 从指令组构建并签名交易
+ * @param group 指令组
+ * @param blockhash 区块哈希
+ * @param signer 签名者
+ */
+export function buildAndSignTransactionFromGroup(group, blockhash, signer) {
+    const tx = buildTransactionFromGroup(group, blockhash, signer.publicKey);
+    tx.sign(signer);
+    return tx;
+}
+// ==================== 单笔转账签名 ====================
+/**
+ * 构建并签名单笔 SOL 转账
+ * @param connection Solana 连接
+ * @param from 发送者 Keypair
+ * @param to 接收者地址
+ * @param amount lamports
+ */
+export async function signTransferSOL(connection, from, to, amount) {
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('finalized');
+    const transaction = new Transaction().add(buildTransferInstruction(from.publicKey, to, amount));
+    transaction.recentBlockhash = blockhash;
+    transaction.feePayer = from.publicKey;
+    transaction.sign(from);
+    const serialized = transaction.serialize();
+    return {
+        data: Buffer.from(serialized).toString('base64'),
+        signature: transaction.signature ? Buffer.from(transaction.signature).toString('base64') : '',
+        transfers: [{ to, amount }],
+        recentBlockhash: blockhash,
+        lastValidBlockHeight,
+    };
+}
+/**
+ * 构建并签名单笔 SOL 转账（使用 SOL 数量）
+ */
+export async function signTransferSOLAmount(connection, from, to, solAmount) {
+    const lamports = solToLamports(solAmount);
+    return signTransferSOL(connection, from, to, lamports);
+}
+// ==================== 批量转账签名 ====================
+/**
+ * 构建并签名批量转账（单笔交易，多个指令）
+ * 单笔交易最多约 20-30 个转账
+ * @param connection Solana 连接
+ * @param from 发送者 Keypair
+ * @param transfers 转账列表
+ */
+export async function signBatchTransferSOL(connection, from, transfers) {
+    if (transfers.length === 0) {
+        throw new Error('No transfers provided');
+    }
+    if (transfers.length > 20) {
+        throw new Error(`Too many transfers (${transfers.length}). Max 20 per transaction. Use signBatchTransferSOLMultiple instead.`);
+    }
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('finalized');
+    const transaction = new Transaction();
+    for (const transfer of transfers) {
+        transaction.add(buildTransferInstruction(from.publicKey, transfer.to, transfer.amount));
+    }
+    transaction.recentBlockhash = blockhash;
+    transaction.feePayer = from.publicKey;
+    transaction.sign(from);
+    const serialized = transaction.serialize();
+    return {
+        data: Buffer.from(serialized).toString('base64'),
+        signature: transaction.signature ? Buffer.from(transaction.signature).toString('base64') : '',
+        transfers,
+        recentBlockhash: blockhash,
+        lastValidBlockHeight,
+    };
+}
+/**
+ * 构建并签名批量转账（多笔交易）
+ * 自动分批处理大量转账
+ * @param connection Solana 连接
+ * @param from 发送者 Keypair
+ * @param transfers 转账列表
+ * @param batchSize 每批大小（默认 20）
+ */
+export async function signBatchTransferSOLMultiple(connection, from, transfers, batchSize = 20) {
+    if (transfers.length === 0) {
+        throw new Error('No transfers provided');
+    }
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('finalized');
+    const transactions = [];
+    // 分批处理
+    for (let i = 0; i < transfers.length; i += batchSize) {
+        const batch = transfers.slice(i, i + batchSize);
+        const transaction = new Transaction();
+        for (const transfer of batch) {
+            transaction.add(buildTransferInstruction(from.publicKey, transfer.to, transfer.amount));
+        }
+        transaction.recentBlockhash = blockhash;
+        transaction.feePayer = from.publicKey;
+        transaction.sign(from);
+        const serialized = transaction.serialize();
+        transactions.push({
+            data: Buffer.from(serialized).toString('base64'),
+            signature: transaction.signature ? Buffer.from(transaction.signature).toString('base64') : '',
+            transfers: batch,
+            recentBlockhash: blockhash,
+            lastValidBlockHeight,
+        });
+    }
+    return {
+        transactions,
+        totalTransfers: transfers.length,
+        totalTransactions: transactions.length,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * 签名多钱包转账（每个钱包一笔交易）
+ * 用于归集或分发场景
+ * @param connection Solana 连接
+ * @param transfers 转账列表
+ */
+export async function signMultiWalletTransfers(connection, transfers) {
+    if (transfers.length === 0) {
+        throw new Error('No transfers provided');
+    }
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash('finalized');
+    const transactions = [];
+    for (const transfer of transfers) {
+        const transaction = new Transaction().add(buildTransferInstruction(transfer.from.publicKey, transfer.to, transfer.amount));
+        transaction.recentBlockhash = blockhash;
+        transaction.feePayer = transfer.from.publicKey;
+        transaction.sign(transfer.from);
+        const serialized = transaction.serialize();
+        transactions.push({
+            data: Buffer.from(serialized).toString('base64'),
+            signature: transaction.signature ? Buffer.from(transaction.signature).toString('base64') : '',
+            transfers: [{ to: transfer.to, amount: transfer.amount }],
+            recentBlockhash: blockhash,
+            lastValidBlockHeight,
+        });
+    }
+    return {
+        transactions,
+        totalTransfers: transfers.length,
+        totalTransactions: transactions.length,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * 归集 SOL（多个钱包转到一个地址）
+ * @param connection Solana 连接
+ * @param wallets 钱包列表
+ * @param toAddress 目标地址
+ * @param amounts 每个钱包转账金额（lamports），如果为空则转全部（保留 5000 lamports 作为手续费）
+ */
+export async function signCollectSOL(connection, wallets, toAddress, amounts) {
+    const transfers = [];
+    for (let i = 0; i < wallets.length; i++) {
+        const wallet = wallets[i];
+        let amount;
+        if (amounts && amounts[i] !== undefined) {
+            amount = amounts[i];
+        }
+        else {
+            // 查询余额，保留 5000 lamports 作为手续费
+            const balance = await connection.getBalance(wallet.publicKey);
+            const reserved = BigInt(5000);
+            amount = BigInt(balance) > reserved ? BigInt(balance) - reserved : BigInt(0);
+        }
+        if (amount > 0) {
+            transfers.push({
+                from: wallet,
+                to: toAddress,
+                amount,
+            });
+        }
+    }
+    return signMultiWalletTransfers(connection, transfers);
+}
+/**
+ * 分发 SOL（一个钱包转到多个地址）
+ * @param connection Solana 连接
+ * @param from 发送者 Keypair
+ * @param distributions 分发列表
+ */
+export async function signDistributeSOL(connection, from, distributions) {
+    // 使用批量转账
+    return signBatchTransferSOLMultiple(connection, from, distributions);
+}
+// ==================== 工具函数 ====================
+/**
+ * 将签名结果转换为后端 API 格式
+ */
+export function toBackendFormat(result) {
+    return {
+        transactions: result.transactions.map(tx => ({
+            data: tx.data,
+            signature: tx.signature,
+        })),
+        totalTransfers: result.totalTransfers,
+        totalTransactions: result.totalTransactions,
+        timestamp: result.createdAt,
+    };
+}

package/dist/sol/utils/wallet.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Solana 钱包工具
+ * @module sol/utils/wallet
+ */
+import { Keypair, PublicKey } from '@solana/web3.js';
+import type { WalletGenerateResult } from '../types.js';
+/**
+ * 批量生成钱包的详细结果
+ */
+export interface BatchWalletGenerateResult {
+    wallets: WalletGenerateResult[];
+    count: number;
+    /** 所有地址列表（方便使用） */
+    addresses: string[];
+    /** 所有私钥列表（base58） */
+    secretKeys: string[];
+    /** Keypair 对象列表（方便直接使用） */
+    keypairs: Keypair[];
+}
+/**
+ * 生成新的 Solana 钱包
+ * @returns 钱包信息
+ */
+export declare function generateKeypair(): WalletGenerateResult;
+/**
+ * 批量生成钱包
+ * @param count 数量
+ * @returns 钱包列表
+ */
+export declare function generateKeypairs(count: number): WalletGenerateResult[];
+/**
+ * 批量生成钱包（增强版，返回更多信息）
+ * @param count 数量
+ * @returns 详细结果
+ */
+export declare function batchGenerateWallets(count: number): BatchWalletGenerateResult;
+/**
+ * 从私钥列表批量导入钱包
+ * @param secretKeys 私钥列表（base58 字符串）
+ * @returns 导入结果
+ */
+export declare function batchImportWallets(secretKeys: string[]): {
+    keypairs: Keypair[];
+    addresses: string[];
+    failed: Array<{
+        index: number;
+        secretKey: string;
+        error: string;
+    }>;
+};
+/**
+ * 从私钥导入钱包
+ * @param secretKey 私钥（Uint8Array 或 base58 字符串）
+ * @returns Keypair
+ */
+export declare function keypairFromSecretKey(secretKey: Uint8Array | string): Keypair;
+/**
+ * 导出私钥为 base58 格式
+ * @param keypair Keypair
+ * @returns base58 编码的私钥
+ */
+export declare function exportSecretKey(keypair: Keypair): string;
+/**
+ * 导出私钥为 Uint8Array
+ * @param keypair Keypair
+ * @returns Uint8Array 私钥
+ */
+export declare function exportSecretKeyArray(keypair: Keypair): Uint8Array;
+/**
+ * 验证 Solana 地址格式
+ * @param address 地址字符串
+ * @returns 是否有效
+ */
+export declare function isValidAddress(address: string): boolean;
+/**
+ * 验证私钥格式
+ * @param secretKey 私钥（base58 字符串）
+ * @returns 是否有效
+ */
+export declare function isValidSecretKey(secretKey: string): boolean;
+/**
+ * 从私钥获取公钥/地址
+ * @param secretKey 私钥（Uint8Array 或 base58 字符串）
+ * @returns 公钥地址
+ */
+export declare function getAddressFromSecretKey(secretKey: Uint8Array | string): string;
+/**
+ * 创建 PublicKey 对象
+ * @param address 地址字符串
+ * @returns PublicKey
+ */
+export declare function toPublicKey(address: string): PublicKey;
+/**
+ * 比较两个地址是否相同
+ * @param addr1 地址1
+ * @param addr2 地址2
+ * @returns 是否相同
+ */
+export declare function isSameAddress(addr1: string, addr2: string): boolean;
+/**
+ * 缩短地址显示
+ * @param address 完整地址
+ * @param prefixLength 前缀长度（默认4）
+ * @param suffixLength 后缀长度（默认4）
+ * @returns 缩短后的地址
+ */
+export declare function shortenAddress(address: string, prefixLength?: number, suffixLength?: number): string;