# @3land/listings-sdk 中文文档 规范地址：https://npmcn.com/package/%403land/listings-sdk/ 版本：0\.0\.7 npm 元数据更新时间：2025-01-24T17:26:08.553Z 中文译文更新时间：2026-11-06T20:18:13.955Z 软件包许可：ISC 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%403land/listings-sdk 原文对照：https://npmcn.com/package/%403land/listings-sdk/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：21.3 MB，1208 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：18 个 - 首次发布：2025-01-03T23:18:42.472Z - 最新版本发布：2025-01-24T17:26:08.392Z - 近 30 天下载量：2379（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：7（近 12 个月 0 个） ## 中文简介 与 3land 的 solana 程序互动的 sdk ## 安装 ```sh npm install @3land/listings-sdk ``` 也可以使用：`pnpm add @3land/listings-sdk`、`yarn add @3land/listings-sdk`、`bun add @3land/listings-sdk` ## README # 3 Land Solana SDK 软件 一个与3Land的索拉纳程序互动的节点Js SDK. 这个SDK提供了一个简单而直观的方法,可以与3Land在索拉纳区块链上的智能合同相融合. ## 目录 1. [先决条件](https://npmcn.com/package/%403land/listings-sdk/#readme-prerequisites) 2. [安装](https://npmcn.com/package/%403land/listings-sdk/#readme-installation) 3. [网络配置](https://npmcn.com/package/%403land/listings-sdk/#readme-network-configuration) - [基本网络选择](https://npmcn.com/package/%403land/listings-sdk/#readme-basic-network-selection) - [自定义配置](https://npmcn.com/package/%403land/listings-sdk/#readme-custom-configuration) - [环境设置](https://npmcn.com/package/%403land/listings-sdk/#readme-environment-specific-setup) 4. [钱包设置](https://npmcn.com/package/%403land/listings-sdk/#readme-wallet-setup) - [Devnet 设置](https://npmcn.com/package/%403land/listings-sdk/#readme-devnet-wallet-setup) - [主网设置](https://npmcn.com/package/%403land/listings-sdk/#readme-mainnet-wallet-setup) 5. [使用量](https://npmcn.com/package/%403land/listings-sdk/#readme-usage) - [创建存储](https://npmcn.com/package/%403land/listings-sdk/#readme-creating-a-store) - [创建收藏](https://npmcn.com/package/%403land/listings-sdk/#readme-creating-a-collection) - [创建单版 NFT](https://npmcn.com/package/%403land/listings-sdk/#readme-creating-a-single-edition-nft) - [购买NFT](https://npmcn.com/package/%403land/listings-sdk/#readme-buying-an-nft) 6. [特征](https://npmcn.com/package/%403land/listings-sdk/#readme-features) 7. [处理错误](https://npmcn.com/package/%403land/listings-sdk/#readme-error-handling) 8. [捐款](https://npmcn.com/package/%403land/listings-sdk/#readme-contributing) 9. [支助](https://npmcn.com/package/%403land/listings-sdk/#readme-support) 10. [许可证](https://npmcn.com/package/%403land/listings-sdk/#readme-license) ## 先决条件 在使用此 SDK 之前, 请保证您安装以下设备 : - 节点.js(v16或更高) - npm 或纱线 - [索拉纳CLI 工具](https://docs.solana.com/cli/install-solana-cli-tools) ## 安装 清除还原 ```bash git clone https://github.com/biccsdev/3land_sdk.git # or npm install 3land_sdk ``` 运行此命令以安装 sdk 所需的所有软件包 ```bash npm install # or yarn add ``` ## 网络配置 ### 基本网络选择 ```typescript import { Store, NetworkType } from "@3land/solana-sdk"; // For Devnet (default) const devnetStore = new Store(); // For Mainnet const mainnetStore = new Store({ network: NetworkType.MAINNET, }); ``` ### 自定义配置 ```typescript // Using custom RPC endpoint const store = new Store({ network: NetworkType.MAINNET, customEndpoint: "https://your-custom-rpc.com", }); // Using custom configuration const storeWithCustomConfig = new Store({ network: NetworkType.MAINNET, customConfig: { programId: "your_custom_program_id", // other config options... }, }); ``` ### 环境设置 ```typescript import dotenv from "dotenv"; dotenv.config(); const store = new Store({ network: (process.env.SOLANA_NETWORK as NetworkType) || NetworkType.DEVNET, customEndpoint: process.env.SOLANA_RPC_ENDPOINT, customConfig: { programId: process.env.PROGRAM_ID, }, }); ``` 示例 `.env` 文件 : ```env SOLANA_NETWORK=mainnet-beta SOLANA_RPC_ENDPOINT=https://your-custom-rpc.com PROGRAM_ID=your_program_id ``` ## 钱包设置 ### Devnet 钱包设置 ```bash solana-keygen new --outfile ~/.config/solana/devnet-wallet.json solana config set --url https://api.devnet.solana.com solana config set --keypair ~/.config/solana/devnet-wallet.json solana airdrop 2 ``` ### 主网钱包设置 ```bash solana-keygen new --outfile ~/.config/solana/mainnet-wallet.json solana config set --url https://api.mainnet-beta.solana.com solana config set --keypair ~/.config/solana/mainnet-wallet.json ``` ## 使用量 ### 创建存储 ```typescript import { StoreConfig, FeeType } from "@3land/solana-sdk"; import { BN } from "bn.js"; try { const storeConfig: StoreConfig = { fee: new BN(1000000), // Fee in lamports feePercentage: 5, // Must be between 0-100 feeType: new FeeType.AllMints(), trust: payer.publicKey, rules: [], }; // Creator and storeId are optional, will default to payer.publicKey and random number const createStoreTxId = await store.createStore( walletKeypair, "My 3Land Store", storeConfig ); console.log("Store created successfully:", createStoreTxId); } catch (error) { if (error.name === "ValidationError") { console.error("Invalid parameters:", error.message); } else { console.error("Store creation failed:", error); } } ``` ### 创建收藏 ```typescript try { const creator = new Creator({ address: payer.publicKey, verified: false, share: 100, }); const metadata = { symbol: "LAND", // Max 10 characters name: "3Land Collection", // Max 32 characters uri: "", sellerFeeBasisPoints: new BN(0), creators: [creator], collection: null, uses: null, }; / Prepare your image files const imageBuffer = fs.readFileSync("path/to/image.gif").buffer; const coverBuffer = fs.readFileSync("path/to/cover.jpeg").buffer; const collectionOptions = { symbol: "SDK", metadata: { name: metadata.name, description: "3Land Collection Description", files: { file: { arrayBuffer() { return imageBuffer; }, type: "image/png", }, cover: { arrayBuffer() { return coverBuffer; }, type: "image/png", }, }, }, creators: metadata.creators, traits: [{ attribute1: "value1" }, { attribute2: "value2" }], sellerFeeBasisPoints: metadata.sellerFeeBasisPoints, }; const collectionTx = await store.createCollection( walletKeypair, { __kind: "V1", size: 0 }, metadata, { options: collectionOptions }, false, // Mutable flag (optional) 0 // Supply (optional) ); console.log("Collection created successfully:", collectionTx); } catch (error) { console.error("Collection creation failed:", error); } ``` ### 创建单版 NFT ```typescript try { const metadata = { name: "My 3Land NFT", uri: "", uriType: 1, sellerFeeBasisPoints: 500, collection: collectionPublicKey, creators: [creator], }; const saleConfig = { prices: [ { amount: new BN(1000000), priceType: new CurrencyType.Native(), }, ], priceType: new PriceRule.None(), rules: [], sendToVault: 0, saleType: new SaleType.Normal(), }; const singleEditionTx = await store.createSingleEdition( walletKeypair, storeAccount, 100, // Supply metadata, saleConfig, [1, 0, 0], // Category [1, 0], // Super Category 0, // Event Category 12345, // Hash Traits collectionPublicKey, { options: nftOptions, } ); console.log("Single edition created successfully:", singleEditionTx); } catch (error) { console.error("Single edition creation failed:", error); } ``` ### 购买NFT ```typescript try { // Most parameters are optional and have default values const buyTx = await store.buySingleEdition( walletKeypair, [0, 0, 0, 0, 0, 0], // Distribution bumps itemAddress // The NFT's item account address ); console.log("Purchase successful:", buyTx); } catch (error) { console.error("Purchase failed:", error); } ``` ## 特征 - **存储管理** - 创建和配置 NFT 商店 - 设置自定义收费结构 - **收藏管理** - 创建 NFT 收藏 - 配置收藏元数据 - **NFT 操作** - 薄荷单版 NFT - 配置 NFT 元数据 - 制定定价和销售规则 - 处理NFT采购 - **内建验证** - 输入参数验证 - 交易错误处理 - 完整错误消息 - **分散储存** - 与Irys整合用于元数据存储 - 支持各种文件类型(jpeg, png, glb, mp3, mp4) - 自动 URI 生成 ### 错误类型 ```typescript try { // SDK operations } catch (error) { if (error.name === "ValidationError") { // Handle validation errors console.error("Invalid parameters:", error.message); } else if (error instanceof SendTransactionError) { // Handle Solana transaction errors console.error("Transaction failed:", error.logs); } else { // Handle other errors console.error("Operation failed:", error); } } ``` ## 捐款 1. 叉子存储器 2. 创建您的特性分支( E)`git checkout -b feature/amazing-feature`(中文(简体) ) 3. 提交更改( E)`git commit -m 'Add some amazing feature'`(中文(简体) ) 4. 推向分行(`git push origin feature/amazing-feature`(中文(简体) ) 5. 打开拉请求 ## 支助 请在 GitHub 寄存器中创建一个问题或直接与 3Land 团队联系. ## 许可证 这个项目根据麻省理工学院许可证获得许可----详情见LICENSE文件. ## 常见问题 ### @3land/listings-sdk 是什么？ 与 3land 的 solana 程序互动的 sdk ### 如何安装 @3land/listings-sdk？ 在项目目录运行 npm install @3land/listings-sdk，或使用 pnpm add / yarn add / bun add。 ### @3land/listings-sdk 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @3land/listings-sdk 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @3land/listings-sdk 可以商用吗？ @3land/listings-sdk 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @3land/listings-sdk 的下载量有多少？ 根据 npm 官方下载统计，@3land/listings-sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,379 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @3land/listings-sdk 还在维护吗？ 最新版本 0\.0\.7 发布于 2025/01/25（1\.8 年前）；至今共发布 7 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/01/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。