four-flap-meme-sdk 3.0.0 → 4.0.0

package/dist/domains/flap/vault/query.js

@@ -0,0 +1,104 @@
+/**
+ * Flap Tax Vaults — 链上查询（query）
+ */
+import { Contract } from 'ethers';
+import { getErrorMessageFromUnknown } from '../../../core/index.js';
+import { VAULT_FACTORY_V2_ABI, VAULT_BASE_V2_ABI, VAULT_BASE_ABI, VAULT_PORTAL_ABI, } from './constants.js';
+import { mapFieldDescriptor, mapVaultMethodSchema, } from './types.js';
+/**
+ * 从 VaultFactory 合约读取 vaultDataSchema
+ */
+export async function queryVaultDataSchema(provider, factoryAddress) {
+    try {
+        const factory = new Contract(factoryAddress, VAULT_FACTORY_V2_ABI, provider);
+        const raw = (await factory.vaultDataSchema());
+        return {
+            description: raw.description,
+            fields: raw.fields.map(mapFieldDescriptor),
+            isArray: raw.isArray,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 从金库合约读取 vaultUISchema
+ */
+export async function queryVaultUISchema(provider, vaultAddress) {
+    try {
+        const vault = new Contract(vaultAddress, VAULT_BASE_V2_ABI, provider);
+        const raw = (await vault.vaultUISchema());
+        return {
+            vaultType: raw.vaultType,
+            description: raw.description,
+            methods: raw.methods.map(mapVaultMethodSchema),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 读取金库合约的动态描述
+ */
+export async function queryVaultDescription(provider, vaultAddress) {
+    try {
+        const vault = new Contract(vaultAddress, VAULT_BASE_ABI, provider);
+        return await vault.description();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 验证合约是否是有效的 VaultFactory
+ */
+export async function validateVaultFactory(provider, factoryAddress) {
+    try {
+        const code = await provider.getCode(factoryAddress);
+        if (code === '0x' || code === '0x0') {
+            return { isValid: false, isV2: false, schema: null, error: '地址没有部署合约' };
+        }
+        const schema = await queryVaultDataSchema(provider, factoryAddress);
+        return {
+            isValid: true,
+            isV2: schema !== null,
+            schema,
+        };
+    }
+    catch (e) {
+        return { isValid: false, isV2: false, schema: null, error: getErrorMessageFromUnknown(e) };
+    }
+}
+/**
+ * 从 VaultPortal 查询代币的金库信息
+ */
+export async function getVaultInfo(provider, vaultPortalAddress, taxTokenAddress) {
+    try {
+        const portal = new Contract(vaultPortalAddress, VAULT_PORTAL_ABI, provider);
+        const info = (await portal.getVault(taxTokenAddress));
+        return {
+            vault: info.vault,
+            vaultFactory: info.vaultFactory,
+            description: info.description,
+            isOfficial: info.isOfficial,
+            riskLevel: Number(info.riskLevel),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 验证合约是否有效（是否部署了代码）
+ */
+export async function isValidContract(provider, address) {
+    try {
+        const code = await provider.getCode(address);
+        return code !== '0x' && code !== '0x0';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/domains/flap/vault/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Flap Tax Vaults — 类型定义
+ */
+/**
+ * FieldDescriptor — 字段描述符
+ * 对应 Solidity 结构体 IVaultSchemasV1.FieldDescriptor
+ */
+export interface FieldDescriptor {
+    name: string;
+    fieldType: string;
+    description: string;
+    decimals: number;
+}
+/**
+ * VaultDataSchema — 工厂数据模式
+ * 对应 VaultFactoryBaseV2.vaultDataSchema() 返回值
+ */
+export interface VaultDataSchema {
+    description: string;
+    fields: FieldDescriptor[];
+    isArray: boolean;
+}
+/**
+ * ApproveAction — ERC-20 授权操作
+ */
+export interface ApproveAction {
+    tokenType: string;
+    amountFieldName: string;
+}
+/**
+ * VaultMethodSchema — 金库方法描述
+ */
+export interface VaultMethodSchema {
+    name: string;
+    description: string;
+    inputs: FieldDescriptor[];
+    outputs: FieldDescriptor[];
+    approvals: ApproveAction[];
+    isInputArray: boolean;
+    isOutputArray: boolean;
+    isWriteMethod: boolean;
+}
+/**
+ * VaultUISchema — 金库 UI 模式
+ */
+export interface VaultUISchema {
+    vaultType: string;
+    description: string;
+    methods: VaultMethodSchema[];
+}
+/** ABI 编码支持的字段值类型 */
+export type AbiEncodeValue = string | number | boolean | bigint;
+/** 链上 vaultDataSchema 原始返回值 */
+export interface RawFieldDescriptor {
+    name: string;
+    fieldType: string;
+    description: string;
+    decimals: bigint | number;
+}
+export interface RawVaultDataSchema {
+    description: string;
+    fields: RawFieldDescriptor[];
+    isArray: boolean;
+}
+export interface RawApproveAction {
+    tokenType: string;
+    amountFieldName: string;
+}
+export interface RawVaultMethodSchema {
+    name: string;
+    description: string;
+    inputs: RawFieldDescriptor[];
+    outputs: RawFieldDescriptor[];
+    approvals: RawApproveAction[];
+    isInputArray: boolean;
+    isOutputArray: boolean;
+    isWriteMethod: boolean;
+}
+export interface RawVaultUISchema {
+    vaultType: string;
+    description: string;
+    methods: RawVaultMethodSchema[];
+}
+export interface RawVaultPortalInfo {
+    vault: string;
+    vaultFactory: string;
+    description: string;
+    isOfficial: boolean;
+    riskLevel: bigint | number;
+}
+export declare function mapFieldDescriptor(f: RawFieldDescriptor): FieldDescriptor;
+export declare function mapApproveAction(a: RawApproveAction): ApproveAction;
+export declare function mapVaultMethodSchema(m: RawVaultMethodSchema): VaultMethodSchema;
+/**
+ * 金库类型枚举
+ *
+ * ⚠️ 基于 flap.sh 实际 JS 源码中 taxVaults.vaultTypes[] 配置
+ * 每种类型对应一个 VaultFactory 合约地址
+ */
+export type VaultType = 'none' | 'gift' | 'split' | 'buyback_burn' | 'burnToEarn' | 'buildYourVault';
+/**
+ * Tax Vault 创建配置
+ *
+ * ⚠️ 金库模式下的核心参数：
+ *   - vaultFactory: VaultFactory 合约地址（直接传递给 VaultPortal）
+ *   - vaultData: ABI 编码的金库初始化数据（由 vaultDataSchema 决定格式）
+ *   - extensionID 和 extensionData 始终为零值
+ */
+export interface TaxVaultConfig {
+    /** 金库类型 */
+    vaultType: VaultType;
+    /**
+     * VaultFactory 合约地址
+     * - 官方金库：从 VAULT_FACTORY_ADDRESSES 自动获取
+     * - buildYourVault：用户手动输入
+     */
+    factoryAddress?: string;
+    /**
+     * 金库初始化数据（原始 hex）
+     * 直接使用此数据作为 vaultData
+     */
+    rawVaultData?: string;
+    /**
+     * 金库数据字段值
+     * key = vaultDataSchema 中 field.name, value = 用户输入
+     */
+    vaultDataFields?: Record<string, string | number | boolean>;
+    /**
+     * 工厂的 vaultDataSchema
+     */
+    vaultDataSchema?: VaultDataSchema;
+}
+/**
+ * 金库信息（链上查询结果）
+ */
+export interface VaultInfo {
+    /** 金库合约地址 */
+    address: string;
+    /** 金库中的原生代币余额 */
+    nativeBalance: bigint;
+    /** 金库描述 */
+    description: string | null;
+    /** 是否为 V2 金库 */
+    isV2: boolean;
+    /** V2 金库的 UI 模式 */
+    uiSchema: VaultUISchema | null;
+}

package/dist/domains/flap/vault/types.js

@@ -0,0 +1,29 @@
+/**
+ * Flap Tax Vaults — 类型定义
+ */
+export function mapFieldDescriptor(f) {
+    return {
+        name: f.name,
+        fieldType: f.fieldType,
+        description: f.description,
+        decimals: Number(f.decimals),
+    };
+}
+export function mapApproveAction(a) {
+    return {
+        tokenType: a.tokenType,
+        amountFieldName: a.amountFieldName,
+    };
+}
+export function mapVaultMethodSchema(m) {
+    return {
+        name: m.name,
+        description: m.description,
+        inputs: m.inputs.map(mapFieldDescriptor),
+        outputs: m.outputs.map(mapFieldDescriptor),
+        approvals: m.approvals.map(mapApproveAction),
+        isInputArray: m.isInputArray,
+        isOutputArray: m.isOutputArray,
+        isWriteMethod: m.isWriteMethod,
+    };
+}

package/dist/domains/flap/vault.d.ts

@@ -1,417 +1,7 @@
 /**
  * Flap Tax Vaults（税收金库）
  *
- * ⚠️ 重要：基于 flap.sh/launch 实际源码分析，金库模式架构如下：
- *
- * 1. 金库代币通过 VaultPortal 合约创建（不是普通 Portal）
- * 2. 调用函数：VaultPortal.newTaxTokenWithVault(params)
- * 3. 参数中 extensionID/extensionData 始终为零值
- * 4. 真正的金库配置通过 vaultFactory（工厂地址）和 vaultData（ABI 编码数据）传递
- * 5. 每种金库类型对应一个具体的 VaultFactory 合约地址
- *
- * VaultPortal.newTaxTokenWithVault 参数结构：
- *   - 基础参数（与 Portal.newTokenV5 相同）：name, symbol, meta, dexThresh, salt, taxRate,
- *     migratorType, quoteToken, quoteAmt, permitData, extensionID(全零), extensionData("0x"),
- *     dexId, lpFeeProfile, taxDuration, antiFarmerDuration, mktBps, deflationBps, dividendBps,
- *     lpBps, minimumShareBalance
- *   - 金库专属参数：vaultFactory(address), vaultData(bytes)
- *
- * 金库分类（来自 flap.sh 源码）：
- *   官方金库 (official)：
- *     - gift (FlapXVault)：禮物金庫，指定一个地址接收税费
- *     - split (SplitVault)：分配金庫，按比例将税费分配给多个接收者
- *     - buyback & burn (SnowBallVault)：自动回购并销毁代币
- *   社区金库 (community)：
- *     - burnToEarn (BlackHoleVault)：燃燒分紅，燃烧代币以赚取分红奖励
- *     - buildYourVault：構建您的金庫，用户输入自定义 VaultFactory 地址
- *
- * @module vault
- */
-import { type JsonRpcProvider } from 'ethers';
-/**
- * FieldDescriptor — 字段描述符
- * 对应 Solidity 结构体 IVaultSchemasV1.FieldDescriptor
- */
-export interface FieldDescriptor {
-    name: string;
-    fieldType: string;
-    description: string;
-    decimals: number;
-}
-/**
- * VaultDataSchema — 工厂数据模式
- * 对应 VaultFactoryBaseV2.vaultDataSchema() 返回值
- */
-export interface VaultDataSchema {
-    description: string;
-    fields: FieldDescriptor[];
-    isArray: boolean;
-}
-/**
- * ApproveAction — ERC-20 授权操作
- */
-export interface ApproveAction {
-    tokenType: string;
-    amountFieldName: string;
-}
-/**
- * VaultMethodSchema — 金库方法描述
- */
-export interface VaultMethodSchema {
-    name: string;
-    description: string;
-    inputs: FieldDescriptor[];
-    outputs: FieldDescriptor[];
-    approvals: ApproveAction[];
-    isInputArray: boolean;
-    isOutputArray: boolean;
-    isWriteMethod: boolean;
-}
-/**
- * VaultUISchema — 金库 UI 模式
- */
-export interface VaultUISchema {
-    vaultType: string;
-    description: string;
-    methods: VaultMethodSchema[];
-}
-/**
- * 金库类型枚举
- *
- * ⚠️ 基于 flap.sh 实际 JS 源码中 taxVaults.vaultTypes[] 配置
- * 每种类型对应一个 VaultFactory 合约地址
- */
-export type VaultType = 'none' | 'gift' | 'split' | 'buyback_burn' | 'burnToEarn' | 'buildYourVault';
-/**
- * 金库类型显示标签
- */
-export declare const VAULT_TYPE_LABELS: Record<VaultType, string>;
-/**
- * 金库类型分类（对齐 flap.sh 的 category 字段）
- */
-export declare const VAULT_TYPE_CATEGORIES: {
-    official: VaultType[];
-    community: VaultType[];
-};
-/**
- * VaultPortal 合约地址
- *
- * ⚠️ 金库代币通过 VaultPortal 创建，不是普通 Portal
- * 来源：flap.sh/_next/static/chunks/2601-*.js
- */
-export declare const VAULT_PORTAL_ADDRESSES: Record<string, string>;
-/**
- * VaultFactory 合约地址（每种金库类型 + 每条链）
- *
- * ⚠️ 直接从 flap.sh 前端 JS 源码中提取的真实地址
- * 来源：flap.sh/_next/static/chunks/2601-*.js 中 taxVaults.vaultTypes[]
- */
-export declare const VAULT_FACTORY_ADDRESSES: Record<string, Record<string, string>>;
-/**
- * 金库额外配置（如 XVault 的 relayer 端点）
- */
-export declare const VAULT_EXTRA_CONFIG: Record<string, Record<string, Record<string, string>>>;
-/**
- * Flap Guardian 合约地址
- */
-export declare const FLAP_GUARDIAN_ADDRESSES: {
-    readonly BSC: "0x9e27098dcD8844bcc6287a557E0b4D09C86B8a4b";
-};
-/**
- * VaultPortal ABI — newTaxTokenWithVault
- *
- * ⚠️ 从 flap.sh 前端 JS 源码提取的真实 ABI
- * 来源：flap.sh/_next/static/chunks/6288-*.js（VaultPortal 合约 ABI）
- */
-export declare const VAULT_PORTAL_ABI: readonly [{
-    readonly type: "function";
-    readonly name: "newTaxTokenWithVault";
-    readonly inputs: readonly [{
-        readonly name: "params";
-        readonly type: "tuple";
-        readonly internalType: "struct IVaultPortalTypes.NewTaxTokenWithVaultParams";
-        readonly components: readonly [{
-            readonly name: "name";
-            readonly type: "string";
-            readonly internalType: "string";
-        }, {
-            readonly name: "symbol";
-            readonly type: "string";
-            readonly internalType: "string";
-        }, {
-            readonly name: "meta";
-            readonly type: "string";
-            readonly internalType: "string";
-        }, {
-            readonly name: "dexThresh";
-            readonly type: "uint8";
-            readonly internalType: "enum IPortalCommonTypes.DexThreshType";
-        }, {
-            readonly name: "salt";
-            readonly type: "bytes32";
-            readonly internalType: "bytes32";
-        }, {
-            readonly name: "taxRate";
-            readonly type: "uint16";
-            readonly internalType: "uint16";
-        }, {
-            readonly name: "migratorType";
-            readonly type: "uint8";
-            readonly internalType: "enum IPortalTypes.MigratorType";
-        }, {
-            readonly name: "quoteToken";
-            readonly type: "address";
-            readonly internalType: "address";
-        }, {
-            readonly name: "quoteAmt";
-            readonly type: "uint256";
-            readonly internalType: "uint256";
-        }, {
-            readonly name: "permitData";
-            readonly type: "bytes";
-            readonly internalType: "bytes";
-        }, {
-            readonly name: "extensionID";
-            readonly type: "bytes32";
-            readonly internalType: "bytes32";
-        }, {
-            readonly name: "extensionData";
-            readonly type: "bytes";
-            readonly internalType: "bytes";
-        }, {
-            readonly name: "dexId";
-            readonly type: "uint8";
-            readonly internalType: "enum IPortalTypes.DEXId";
-        }, {
-            readonly name: "lpFeeProfile";
-            readonly type: "uint8";
-            readonly internalType: "enum IPortalTypes.V3LPFeeProfile";
-        }, {
-            readonly name: "taxDuration";
-            readonly type: "uint64";
-            readonly internalType: "uint64";
-        }, {
-            readonly name: "antiFarmerDuration";
-            readonly type: "uint64";
-            readonly internalType: "uint64";
-        }, {
-            readonly name: "mktBps";
-            readonly type: "uint16";
-            readonly internalType: "uint16";
-        }, {
-            readonly name: "deflationBps";
-            readonly type: "uint16";
-            readonly internalType: "uint16";
-        }, {
-            readonly name: "dividendBps";
-            readonly type: "uint16";
-            readonly internalType: "uint16";
-        }, {
-            readonly name: "lpBps";
-            readonly type: "uint16";
-            readonly internalType: "uint16";
-        }, {
-            readonly name: "minimumShareBalance";
-            readonly type: "uint256";
-            readonly internalType: "uint256";
-        }, {
-            readonly name: "vaultFactory";
-            readonly type: "address";
-            readonly internalType: "address";
-        }, {
-            readonly name: "vaultData";
-            readonly type: "bytes";
-            readonly internalType: "bytes";
-        }];
-    }];
-    readonly outputs: readonly [{
-        readonly name: "token";
-        readonly type: "address";
-        readonly internalType: "address";
-    }];
-    readonly stateMutability: "payable";
-}, {
-    readonly type: "function";
-    readonly name: "getVault";
-    readonly inputs: readonly [{
-        readonly name: "taxToken";
-        readonly type: "address";
-        readonly internalType: "address";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "info";
-        readonly type: "tuple";
-        readonly internalType: "struct IVaultPortalTypes.VaultInfo";
-        readonly components: readonly [{
-            readonly name: "vault";
-            readonly type: "address";
-            readonly internalType: "address";
-        }, {
-            readonly name: "vaultFactory";
-            readonly type: "address";
-            readonly internalType: "address";
-        }, {
-            readonly name: "description";
-            readonly type: "string";
-            readonly internalType: "string";
-        }, {
-            readonly name: "isOfficial";
-            readonly type: "bool";
-            readonly internalType: "bool";
-        }, {
-            readonly name: "riskLevel";
-            readonly type: "uint8";
-            readonly internalType: "enum IVaultPortalTypes.RiskLevel";
-        }];
-    }];
-    readonly stateMutability: "view";
-}, {
-    readonly type: "function";
-    readonly name: "predictTaxTokenV1Address";
-    readonly inputs: readonly [{
-        readonly name: "salt";
-        readonly type: "bytes32";
-        readonly internalType: "bytes32";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "predictedAddress";
-        readonly type: "address";
-        readonly internalType: "address";
-    }];
-    readonly stateMutability: "view";
-}];
-/**
- * IVaultFactory ABI（V1）
- */
-export declare const VAULT_FACTORY_ABI: string[];
-/**
- * VaultFactoryBaseV2 ABI
- */
-export declare const VAULT_FACTORY_V2_ABI: string[];
-/**
- * VaultBase ABI（V1）
- */
-export declare const VAULT_BASE_ABI: string[];
-/**
- * VaultBaseV2 ABI
- */
-export declare const VAULT_BASE_V2_ABI: string[];
-/** extensionID/extensionData 在金库模式下始终为零值 */
-export declare const NONE_EXTENSION_ID: string;
-/**
- * Tax Vault 创建配置
- *
- * ⚠️ 金库模式下的核心参数：
- *   - vaultFactory: VaultFactory 合约地址（直接传递给 VaultPortal）
- *   - vaultData: ABI 编码的金库初始化数据（由 vaultDataSchema 决定格式）
- *   - extensionID 和 extensionData 始终为零值
- */
-export interface TaxVaultConfig {
-    /** 金库类型 */
-    vaultType: VaultType;
-    /**
-     * VaultFactory 合约地址
-     * - 官方金库：从 VAULT_FACTORY_ADDRESSES 自动获取
-     * - buildYourVault：用户手动输入
-     */
-    factoryAddress?: string;
-    /**
-     * 金库初始化数据（原始 hex）
-     * 直接使用此数据作为 vaultData
-     */
-    rawVaultData?: string;
-    /**
-     * 金库数据字段值
-     * key = vaultDataSchema 中 field.name, value = 用户输入
-     */
-    vaultDataFields?: Record<string, string | number | boolean>;
-    /**
-     * 工厂的 vaultDataSchema
-     */
-    vaultDataSchema?: VaultDataSchema;
-}
-/**
- * 根据 VaultDataSchema 和用户输入编码 vaultData
- */
-export declare function encodeVaultData(schema: VaultDataSchema, fieldValues: Record<string, string | number | boolean>): string;
-/**
- * 获取指定链和金库类型的 VaultFactory 合约地址
- */
-export declare function getVaultFactoryAddress(chain: string, vaultType: VaultType): string | null;
-/**
- * 获取指定链的 VaultPortal 合约地址
- */
-export declare function getVaultPortalAddress(chain: string): string | null;
-/**
- * 构建金库参数（用于 VaultPortal.newTaxTokenWithVault）
- *
- * ⚠️ 重要：返回的是 vaultFactory 和 vaultData，不是 extensionID/extensionData
- * extensionID/extensionData 在金库模式下始终为零值
- *
- * @returns { vaultFactory, vaultData } 直接传给 VaultPortal
- */
-export declare function buildVaultParams(config?: TaxVaultConfig, chain?: string): {
-    vaultFactory: string;
-    vaultData: string;
-};
-/**
- * 旧版兼容：将 TaxVaultConfig 转换为 extensionID 和 extensionData
- *
- * ⚠️ 注意：真实的 Flap 平台在金库模式下 extensionID/extensionData 始终为零值
- * 金库参数通过 VaultPortal 的 vaultFactory/vaultData 传递
- * 此函数仅用于向后兼容
- */
-export declare function buildVaultExtensionParams(): {
-    extensionID: string;
-    extensionData: string;
-};
-/**
- * 从 VaultFactory 合约读取 vaultDataSchema
- */
-export declare function queryVaultDataSchema(provider: JsonRpcProvider, factoryAddress: string): Promise<VaultDataSchema | null>;
-/**
- * 从金库合约读取 vaultUISchema
- */
-export declare function queryVaultUISchema(provider: JsonRpcProvider, vaultAddress: string): Promise<VaultUISchema | null>;
-/**
- * 读取金库合约的动态描述
- */
-export declare function queryVaultDescription(provider: JsonRpcProvider, vaultAddress: string): Promise<string | null>;
-/**
- * 验证合约是否是有效的 VaultFactory
- */
-export declare function validateVaultFactory(provider: JsonRpcProvider, factoryAddress: string): Promise<{
-    isValid: boolean;
-    isV2: boolean;
-    schema: VaultDataSchema | null;
-    error?: string;
-}>;
-/**
- * 从 VaultPortal 查询代币的金库信息
- */
-export declare function getVaultInfo(provider: JsonRpcProvider, vaultPortalAddress: string, taxTokenAddress: string): Promise<{
-    vault: string;
-    vaultFactory: string;
-    description: string;
-    isOfficial: boolean;
-    riskLevel: number;
-} | null>;
-/**
- * 验证合约是否有效（是否部署了代码）
- */
-export declare function isValidContract(provider: JsonRpcProvider, address: string): Promise<boolean>;
-/**
- * 金库信息（链上查询结果）
+ * 原超长文件按职责拆分为 vault/ 目录下的多个子文件，
+ * 对外 export 符号与路径保持不变（见 vault/index.ts）。
  */
-export interface VaultInfo {
-    /** 金库合约地址 */
-    address: string;
-    /** 金库中的原生代币余额 */
-    nativeBalance: bigint;
-    /** 金库描述 */
-    description: string | null;
-    /** 是否为 V2 金库 */
-    isV2: boolean;
-    /** V2 金库的 UI 模式 */
-    uiSchema: VaultUISchema | null;
-}
+export * from './vault/index.js';