four-flap-meme-sdk 1.5.5 → 1.5.6

package/dist/sol/token/metadata-upload.js

@@ -0,0 +1,173 @@
+/**
+ * 元数据上传（复用 Flap 官方 IPFS 接口）
+ * @module sol/token/metadata-upload
+ */
+// Flap 官方 IPFS API
+const FLAP_IPFS_API = 'https://0pi75kmgw9.execute-api.eu-west-3.amazonaws.com/v1';
+/**
+ * 使用 Flap 官方 GraphQL 接口上传文件到 IPFS
+ * 同时上传图片和元数据，返回 bafkrei... 格式的 CIDv1
+ *
+ * @param file 图片文件（File 或 Uint8Array 或 Buffer）
+ * @param meta 元数据
+ * @returns CID
+ */
+export async function uploadToFlapIPFS(file, meta) {
+    try {
+        const form = new FormData();
+        // 1. 添加文件（key 为 "0"）
+        if (file instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(file))) {
+            const blob = new Blob([file]);
+            form.append('0', blob, 'upload.png');
+        }
+        else {
+            form.append('0', file);
+        }
+        // 2. 添加 GraphQL operations（同时上传图片和元数据）
+        const operations = {
+            query: `
+mutation Create($file: Upload!, $meta: MetadataInput!) {
+  create(file: $file, meta: $meta)
+}
+`,
+            variables: {
+                file: null,
+                meta: {
+                    buy: null,
+                    creator: meta.creator || '0x0000000000000000000000000000000000000000',
+                    description: meta.description || '',
+                    telegram: meta.telegram || null,
+                    twitter: meta.twitter || null,
+                    website: meta.website || null,
+                    sell: null,
+                }
+            }
+        };
+        form.append('operations', JSON.stringify(operations));
+        // 3. 添加 map（将文件映射到 GraphQL 变量）
+        form.append('map', JSON.stringify({ "0": ["variables.file"] }));
+        // 4. 发送请求
+        // 注意：不要手动设置 Content-Type，浏览器/Node 会自动添加正确的 multipart/form-data 和 boundary
+        const resp = await fetch(FLAP_IPFS_API, {
+            method: 'POST',
+            body: form,
+        });
+        if (!resp.ok) {
+            return {
+                success: false,
+                error: `IPFS upload failed: ${resp.status} ${resp.statusText}`,
+            };
+        }
+        const data = await resp.json();
+        const metaCid = data?.data?.create;
+        if (!metaCid) {
+            const errorMsg = data?.errors?.[0]?.message || 'No CID returned';
+            return {
+                success: false,
+                error: `IPFS upload error: ${errorMsg}`,
+            };
+        }
+        return {
+            success: true,
+            cid: metaCid,
+            uri: `ipfs://${metaCid}`,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message,
+        };
+    }
+}
+/**
+ * 上传图片和元数据到 IPFS（Flap 官方接口）
+ * 这是主要的上传方法
+ *
+ * @param imageBuffer 图片 Buffer
+ * @param metadata 代币元数据
+ * @returns 上传结果
+ */
+export async function uploadTokenMetadata(imageBuffer, metadata) {
+    return uploadToFlapIPFS(imageBuffer, {
+        creator: metadata.creator,
+        description: metadata.description,
+        telegram: metadata.telegram,
+        twitter: metadata.twitter,
+        website: metadata.website,
+    });
+}
+/**
+ * 从 File 对象上传（浏览器环境）
+ */
+export async function uploadTokenMetadataFromFile(file, metadata) {
+    return uploadToFlapIPFS(file, {
+        creator: metadata.creator,
+        description: metadata.description,
+        telegram: metadata.telegram,
+        twitter: metadata.twitter,
+        website: metadata.website,
+    });
+}
+/**
+ * 构建完整的 Metaplex 元数据 JSON
+ * 用于已经上传图片后，构建标准的元数据格式
+ */
+export function buildMetaplexMetadataJson(metadata, imageCid) {
+    const imageUri = imageCid.startsWith('ipfs://') ? imageCid : `ipfs://${imageCid}`;
+    return {
+        name: metadata.name,
+        symbol: metadata.symbol,
+        description: metadata.description,
+        image: imageUri,
+        external_url: metadata.externalUrl,
+        attributes: metadata.attributes,
+        properties: {
+            files: [
+                {
+                    uri: imageUri,
+                    type: 'image/png',
+                },
+            ],
+            category: 'image',
+        },
+    };
+}
+/**
+ * 构建元数据 JSON（不上传，用于已有图片 URL 的情况）
+ */
+export function buildMetadataJson(metadata) {
+    return {
+        name: metadata.name,
+        symbol: metadata.symbol,
+        description: metadata.description,
+        image: metadata.image,
+        external_url: metadata.externalUrl,
+        attributes: metadata.attributes,
+        properties: {
+            files: [
+                {
+                    uri: metadata.image,
+                    type: 'image/png',
+                },
+            ],
+            category: 'image',
+        },
+    };
+}
+/**
+ * CID 转换为 IPFS URI
+ */
+export function cidToUri(cid) {
+    if (cid.startsWith('ipfs://')) {
+        return cid;
+    }
+    return `ipfs://${cid}`;
+}
+/**
+ * CID 转换为 HTTP 网关 URL
+ */
+export function cidToHttpUrl(cid, gateway = 'https://ipfs.io/ipfs/') {
+    const cleanCid = cid.replace('ipfs://', '');
+    return `${gateway}${cleanCid}`;
+}

package/dist/sol/token/metadata.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Metaplex Token Metadata 集成
+ * @module sol/token/metadata
+ */
+import { Connection, Keypair, PublicKey, TransactionInstruction } from '@solana/web3.js';
+/**
+ * 元数据账户数据
+ */
+export interface MetadataData {
+    name: string;
+    symbol: string;
+    uri: string;
+    sellerFeeBasisPoints: number;
+    creators?: Array<{
+        address: PublicKey;
+        verified: boolean;
+        share: number;
+    }> | null;
+}
+/**
+ * 获取 Metadata PDA 地址
+ * @param mint Mint 地址
+ */
+export declare function getMetadataPDA(mint: PublicKey): PublicKey;
+/**
+ * 构建 CreateMetadataAccountV3 指令
+ * 手动构建指令，避免 Metaplex SDK 版本兼容问题
+ */
+export declare function buildCreateMetadataAccountV3Instruction(params: {
+    metadata: PublicKey;
+    mint: PublicKey;
+    mintAuthority: PublicKey;
+    payer: PublicKey;
+    updateAuthority: PublicKey;
+    name: string;
+    symbol: string;
+    uri: string;
+    sellerFeeBasisPoints?: number;
+    creators?: Array<{
+        address: PublicKey;
+        verified: boolean;
+        share: number;
+    }> | null;
+    isMutable?: boolean;
+}): TransactionInstruction;
+/**
+ * 构建并签名创建 Metadata 交易
+ * @param connection Solana 连接
+ * @param params 参数
+ */
+export declare function signCreateMetadataTransaction(connection: Connection, params: {
+    mint: PublicKey;
+    mintAuthority: Keypair;
+    payer: Keypair;
+    name: string;
+    symbol: string;
+    uri: string;
+    sellerFeeBasisPoints?: number;
+    creators?: Array<{
+        address: PublicKey;
+        verified: boolean;
+        share: number;
+    }> | null;
+    isMutable?: boolean;
+}): Promise<{
+    success: boolean;
+    metadataAddress?: string;
+    signedTransaction?: {
+        data: string;
+        signature: string;
+    };
+    error?: string;
+}>;
+/**
+ * 构建 UpdateMetadataAccountV2 指令
+ */
+export declare function buildUpdateMetadataAccountV2Instruction(params: {
+    metadata: PublicKey;
+    updateAuthority: PublicKey;
+    newUpdateAuthority?: PublicKey | null;
+    name?: string;
+    symbol?: string;
+    uri?: string;
+    sellerFeeBasisPoints?: number;
+    creators?: Array<{
+        address: PublicKey;
+        verified: boolean;
+        share: number;
+    }> | null;
+    primarySaleHappened?: boolean;
+    isMutable?: boolean;
+}): TransactionInstruction;

package/dist/sol/token/metadata.js

@@ -0,0 +1,274 @@
+/**
+ * Metaplex Token Metadata 集成
+ * @module sol/token/metadata
+ */
+import { PublicKey, Transaction, TransactionInstruction, } from '@solana/web3.js';
+import { SYSTEM_PROGRAMS } from '../constants.js';
+// Metaplex Token Metadata Program ID
+const TOKEN_METADATA_PROGRAM_ID = new PublicKey(SYSTEM_PROGRAMS.METADATA_PROGRAM);
+/**
+ * 获取 Metadata PDA 地址
+ * @param mint Mint 地址
+ */
+export function getMetadataPDA(mint) {
+    const [pda] = PublicKey.findProgramAddressSync([
+        Buffer.from('metadata'),
+        TOKEN_METADATA_PROGRAM_ID.toBuffer(),
+        mint.toBuffer(),
+    ], TOKEN_METADATA_PROGRAM_ID);
+    return pda;
+}
+/**
+ * 构建 CreateMetadataAccountV3 指令
+ * 手动构建指令，避免 Metaplex SDK 版本兼容问题
+ */
+export function buildCreateMetadataAccountV3Instruction(params) {
+    const { metadata, mint, mintAuthority, payer, updateAuthority, name, symbol, uri, sellerFeeBasisPoints = 0, creators = null, isMutable = true, } = params;
+    // 构建指令数据
+    // CreateMetadataAccountV3 指令格式
+    const data = buildCreateMetadataV3Data({
+        name,
+        symbol,
+        uri,
+        sellerFeeBasisPoints,
+        creators,
+        isMutable,
+    });
+    return new TransactionInstruction({
+        keys: [
+            { pubkey: metadata, isSigner: false, isWritable: true },
+            { pubkey: mint, isSigner: false, isWritable: false },
+            { pubkey: mintAuthority, isSigner: true, isWritable: false },
+            { pubkey: payer, isSigner: true, isWritable: true },
+            { pubkey: updateAuthority, isSigner: false, isWritable: false },
+            { pubkey: new PublicKey(SYSTEM_PROGRAMS.SYSTEM_PROGRAM), isSigner: false, isWritable: false },
+            { pubkey: new PublicKey(SYSTEM_PROGRAMS.RENT_SYSVAR), isSigner: false, isWritable: false },
+        ],
+        programId: TOKEN_METADATA_PROGRAM_ID,
+        data,
+    });
+}
+/**
+ * 构建 CreateMetadataAccountV3 指令数据
+ */
+function buildCreateMetadataV3Data(params) {
+    const { name, symbol, uri, sellerFeeBasisPoints, creators, isMutable } = params;
+    // 指令判别器：CreateMetadataAccountV3 = 33
+    const discriminator = 33;
+    // 计算缓冲区大小
+    let size = 1; // discriminator
+    size += 4 + name.length; // name (string with u32 length prefix)
+    size += 4 + symbol.length; // symbol
+    size += 4 + uri.length; // uri
+    size += 2; // sellerFeeBasisPoints (u16)
+    size += 1; // creators option flag
+    if (creators) {
+        size += 4; // creators vec length
+        size += creators.length * (32 + 1 + 1); // each creator: pubkey + verified + share
+    }
+    size += 1; // collection option flag (None)
+    size += 1; // uses option flag (None)
+    size += 1; // isMutable
+    size += 1; // collectionDetails option flag (None)
+    const buffer = Buffer.alloc(size);
+    let offset = 0;
+    // 写入 discriminator
+    buffer.writeUInt8(discriminator, offset);
+    offset += 1;
+    // 写入 name
+    buffer.writeUInt32LE(name.length, offset);
+    offset += 4;
+    buffer.write(name, offset);
+    offset += name.length;
+    // 写入 symbol
+    buffer.writeUInt32LE(symbol.length, offset);
+    offset += 4;
+    buffer.write(symbol, offset);
+    offset += symbol.length;
+    // 写入 uri
+    buffer.writeUInt32LE(uri.length, offset);
+    offset += 4;
+    buffer.write(uri, offset);
+    offset += uri.length;
+    // 写入 sellerFeeBasisPoints
+    buffer.writeUInt16LE(sellerFeeBasisPoints, offset);
+    offset += 2;
+    // 写入 creators
+    if (creators && creators.length > 0) {
+        buffer.writeUInt8(1, offset); // Some
+        offset += 1;
+        buffer.writeUInt32LE(creators.length, offset);
+        offset += 4;
+        for (const creator of creators) {
+            creator.address.toBuffer().copy(buffer, offset);
+            offset += 32;
+            buffer.writeUInt8(creator.verified ? 1 : 0, offset);
+            offset += 1;
+            buffer.writeUInt8(creator.share, offset);
+            offset += 1;
+        }
+    }
+    else {
+        buffer.writeUInt8(0, offset); // None
+        offset += 1;
+    }
+    // 写入 collection (None)
+    buffer.writeUInt8(0, offset);
+    offset += 1;
+    // 写入 uses (None)
+    buffer.writeUInt8(0, offset);
+    offset += 1;
+    // 写入 isMutable
+    buffer.writeUInt8(isMutable ? 1 : 0, offset);
+    offset += 1;
+    // 写入 collectionDetails (None)
+    buffer.writeUInt8(0, offset);
+    offset += 1;
+    return buffer.slice(0, offset);
+}
+/**
+ * 构建并签名创建 Metadata 交易
+ * @param connection Solana 连接
+ * @param params 参数
+ */
+export async function signCreateMetadataTransaction(connection, params) {
+    try {
+        const { mint, mintAuthority, payer, name, symbol, uri, sellerFeeBasisPoints = 0, creators = null, isMutable = true, } = params;
+        // 获取 Metadata PDA
+        const metadataPDA = getMetadataPDA(mint);
+        // 获取 blockhash
+        const { blockhash } = await connection.getLatestBlockhash('finalized');
+        // 构建指令
+        const instruction = buildCreateMetadataAccountV3Instruction({
+            metadata: metadataPDA,
+            mint,
+            mintAuthority: mintAuthority.publicKey,
+            payer: payer.publicKey,
+            updateAuthority: mintAuthority.publicKey,
+            name,
+            symbol,
+            uri,
+            sellerFeeBasisPoints,
+            creators,
+            isMutable,
+        });
+        // 构建交易
+        const transaction = new Transaction();
+        transaction.add(instruction);
+        transaction.recentBlockhash = blockhash;
+        transaction.feePayer = payer.publicKey;
+        // 签名
+        const signers = [payer];
+        if (!payer.publicKey.equals(mintAuthority.publicKey)) {
+            signers.push(mintAuthority);
+        }
+        transaction.sign(...signers);
+        const serialized = transaction.serialize();
+        return {
+            success: true,
+            metadataAddress: metadataPDA.toBase58(),
+            signedTransaction: {
+                data: Buffer.from(serialized).toString('base64'),
+                signature: transaction.signature ? Buffer.from(transaction.signature).toString('base64') : '',
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message,
+        };
+    }
+}
+/**
+ * 构建 UpdateMetadataAccountV2 指令
+ */
+export function buildUpdateMetadataAccountV2Instruction(params) {
+    const { metadata, updateAuthority, newUpdateAuthority, name, symbol, uri, sellerFeeBasisPoints, creators, primarySaleHappened, isMutable, } = params;
+    // UpdateMetadataAccountV2 指令格式
+    // discriminator = 15
+    const discriminator = 15;
+    // 简化版本：只构建基本的更新数据
+    // 完整实现需要更复杂的序列化
+    const dataBuffer = Buffer.alloc(1024);
+    let offset = 0;
+    dataBuffer.writeUInt8(discriminator, offset);
+    offset += 1;
+    // data option (Some if any field is provided)
+    const hasData = name || symbol || uri || sellerFeeBasisPoints !== undefined || creators;
+    dataBuffer.writeUInt8(hasData ? 1 : 0, offset);
+    offset += 1;
+    if (hasData) {
+        // name
+        const nameStr = name || '';
+        dataBuffer.writeUInt32LE(nameStr.length, offset);
+        offset += 4;
+        dataBuffer.write(nameStr, offset);
+        offset += nameStr.length;
+        // symbol
+        const symbolStr = symbol || '';
+        dataBuffer.writeUInt32LE(symbolStr.length, offset);
+        offset += 4;
+        dataBuffer.write(symbolStr, offset);
+        offset += symbolStr.length;
+        // uri
+        const uriStr = uri || '';
+        dataBuffer.writeUInt32LE(uriStr.length, offset);
+        offset += 4;
+        dataBuffer.write(uriStr, offset);
+        offset += uriStr.length;
+        // sellerFeeBasisPoints
+        dataBuffer.writeUInt16LE(sellerFeeBasisPoints || 0, offset);
+        offset += 2;
+        // creators (None for simplicity)
+        dataBuffer.writeUInt8(0, offset);
+        offset += 1;
+        // collection (None)
+        dataBuffer.writeUInt8(0, offset);
+        offset += 1;
+        // uses (None)
+        dataBuffer.writeUInt8(0, offset);
+        offset += 1;
+    }
+    // newUpdateAuthority option
+    if (newUpdateAuthority) {
+        dataBuffer.writeUInt8(1, offset);
+        offset += 1;
+        newUpdateAuthority.toBuffer().copy(dataBuffer, offset);
+        offset += 32;
+    }
+    else {
+        dataBuffer.writeUInt8(0, offset);
+        offset += 1;
+    }
+    // primarySaleHappened option
+    if (primarySaleHappened !== undefined) {
+        dataBuffer.writeUInt8(1, offset);
+        offset += 1;
+        dataBuffer.writeUInt8(primarySaleHappened ? 1 : 0, offset);
+        offset += 1;
+    }
+    else {
+        dataBuffer.writeUInt8(0, offset);
+        offset += 1;
+    }
+    // isMutable option
+    if (isMutable !== undefined) {
+        dataBuffer.writeUInt8(1, offset);
+        offset += 1;
+        dataBuffer.writeUInt8(isMutable ? 1 : 0, offset);
+        offset += 1;
+    }
+    else {
+        dataBuffer.writeUInt8(0, offset);
+        offset += 1;
+    }
+    return new TransactionInstruction({
+        keys: [
+            { pubkey: metadata, isSigner: false, isWritable: true },
+            { pubkey: updateAuthority, isSigner: true, isWritable: false },
+        ],
+        programId: TOKEN_METADATA_PROGRAM_ID,
+        data: dataBuffer.slice(0, offset),
+    });
+}

package/dist/sol/token/types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Token 创建相关类型定义
+ * @module sol/token/types
+ */
+import { PublicKey, Keypair } from '@solana/web3.js';
+/**
+ * 代币标准
+ */
+export type TokenStandard = 'SPL' | 'TOKEN_2022';
+/**
+ * 代币元数据（符合 Metaplex 标准）
+ */
+export interface TokenMetadataInput {
+    /** 代币名称 */
+    name: string;
+    /** 代币符号 */
+    symbol: string;
+    /** 代币描述 */
+    description: string;
+    /** 图片 URL（IPFS 或 HTTP） */
+    image: string;
+    /** 外部链接 */
+    externalUrl?: string;
+    /** 属性 */
+    attributes?: Array<{
+        trait_type: string;
+        value: string | number;
+    }>;
+}
+/**
+ * 上传到 IPFS 的元数据 JSON 格式
+ */
+export interface TokenMetadataJson {
+    name: string;
+    symbol: string;
+    description: string;
+    image: string;
+    external_url?: string;
+    attributes?: Array<{
+        trait_type: string;
+        value: string | number;
+    }>;
+    properties?: {
+        files?: Array<{
+            uri: string;
+            type: string;
+        }>;
+        category?: string;
+    };
+}
+/**
+ * Token-2022 扩展功能
+ */
+export interface Token2022Extensions {
+    /** 转账手续费（基点，如 100 = 1%） */
+    transferFee?: {
+        feeBasisPoints: number;
+        maxFee: bigint;
+    };
+    /** 不可转让 */
+    nonTransferable?: boolean;
+    /** 利息 */
+    interestBearing?: {
+        rate: number;
+    };
+    /** 永久代理 */
+    permanentDelegate?: PublicKey;
+    /** 关闭权限 */
+    closeAuthority?: PublicKey;
+}
+/**
+ * 代币创建参数
+ */
+export interface CreateTokenParams {
+    /** 代币名称 */
+    name: string;
+    /** 代币符号 */
+    symbol: string;
+    /** 代币描述 */
+    description: string;
+    /** 精度（小数位数） */
+    decimals: number;
+    /** 初始供应量（不含精度，如 1000000 表示 100万） */
+    initialSupply: bigint;
+    /** 图片 Buffer（用于上传 IPFS） */
+    imageBuffer?: Buffer;
+    /** 图片文件名 */
+    imageFilename?: string;
+    /** 已上传的图片 URL（如果已有，则不需要 imageBuffer） */
+    imageUrl?: string;
+    /** 创建者 Keypair */
+    creator: Keypair;
+    /** Mint 权限（默认为 creator） */
+    mintAuthority?: PublicKey;
+    /** 冻结权限（null 表示不可冻结） */
+    freezeAuthority?: PublicKey | null;
+    /** 代币标准（默认 TOKEN_2022） */
+    tokenStandard?: TokenStandard;
+    /** Token-2022 扩展功能 */
+    extensions?: Token2022Extensions;
+}
+/**
+ * 代币创建结果
+ */
+export interface CreateTokenResult {
+    /** 是否成功 */
+    success: boolean;
+    /** Mint 地址 */
+    mint?: string;
+    /** Metadata 账户地址 */
+    metadataAddress?: string;
+    /** 元数据 URI（IPFS） */
+    metadataUri?: string;
+    /** 图片 URI（IPFS） */
+    imageUri?: string;
+    /** 签名后的交易数据（用于提交后端） */
+    signedTransactions?: Array<{
+        data: string;
+        signature: string;
+        description: string;
+    }>;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * Mint To 参数
+ */
+export interface MintToParams {
+    /** Mint 地址 */
+    mint: string;
+    /** 目标地址 */
+    destination: string;
+    /** 数量（含精度） */
+    amount: bigint;
+    /** Mint 权限 Keypair */
+    mintAuthority: Keypair;
+    /** 代币标准 */
+    tokenStandard?: TokenStandard;
+}
+/**
+ * Mint To 结果
+ */
+export interface MintToResult {
+    success: boolean;
+    /** ATA 地址 */
+    ataAddress?: string;
+    /** 签名后的交易数据 */
+    signedTransaction?: {
+        data: string;
+        signature: string;
+    };
+    error?: string;
+}

package/dist/sol/token/types.js

@@ -0,0 +1,5 @@
+/**
+ * Token 创建相关类型定义
+ * @module sol/token/types
+ */
+export {};