diff --git a/src/components/products/bubblegum-v2/index.js b/src/components/products/bubblegum-v2/index.js index 0dfcdd717..bc7c769ec 100644 --- a/src/components/products/bubblegum-v2/index.js +++ b/src/components/products/bubblegum-v2/index.js @@ -58,6 +58,10 @@ export const bubblegumv2 = { href: '/smart-contracts/bubblegum-v2/mint-cnfts', }, { title: 'Fetching cNFTs', href: '/smart-contracts/bubblegum-v2/fetch-cnfts' }, + { + title: 'Reading Inherited Royalties', + href: '/smart-contracts/bubblegum-v2/reading-inherited-royalties', + }, { title: 'Transferring cNFTs', href: '/smart-contracts/bubblegum-v2/transfer-cnfts' }, { title: 'Freeze and Thaw cNFTs', href: '/smart-contracts/bubblegum-v2/freeze-cnfts' }, { title: 'Updating cNFTs', href: '/smart-contracts/bubblegum-v2/update-cnfts' }, @@ -152,6 +156,11 @@ export const bubblegumv2 = { ko: 'cNFT 가져오기', zh: '获取cNFT' }, + 'Reading Inherited Royalties': { + ja: '継承ロイヤリティの読み取り', + ko: '상속 로열티 읽기', + zh: '读取继承版税' + }, 'Transferring cNFTs': { ja: 'cNFTの転送', ko: 'cNFT 전송', diff --git a/src/examples/bubblegum/get-asset-with-proof-inherited/index.js b/src/examples/bubblegum/get-asset-with-proof-inherited/index.js new file mode 100644 index 000000000..bd6294e6f --- /dev/null +++ b/src/examples/bubblegum/get-asset-with-proof-inherited/index.js @@ -0,0 +1,32 @@ +/** + * Example: getAssetWithProof with inherited royalties + * + * Leaf metadata keeps the on-chain sentinel; DAS main royalty fields hold the collection-resolved display rate. + * + * This file is auto-generated by scripts/build-examples.js + * Edit the native .js/.ts and .rs files, then run: node scripts/build-examples.js + */ + +const umiSections = { + "imports": "import { getAssetWithProof, mplBubblegum } from '@metaplex-foundation/mpl-bubblegum'\nimport { publicKey } from '@metaplex-foundation/umi'\nimport { createUmi } from '@metaplex-foundation/umi-bundle-defaults'", + "setup": "const umi = createUmi('https://api.devnet.solana.com').use(mplBubblegum())\n\nconst assetId = publicKey('YOUR_ASSET_ID')", + "main": "const assetWithProof = await getAssetWithProof(umi, assetId, {\n truncateCanopy: true,\n})\n\n// Leaf / hashing value (65535 when inherited)\nconsole.log(assetWithProof.metadata.sellerFeeBasisPoints)\n\n// Display / payout value from DAS main fields\nconsole.log(assetWithProof.rpcAsset.royalty?.basis_points)", + "output": "// 65535\n// 500", + "full": "// [IMPORTS]\nimport { getAssetWithProof, mplBubblegum } from '@metaplex-foundation/mpl-bubblegum'\nimport { publicKey } from '@metaplex-foundation/umi'\nimport { createUmi } from '@metaplex-foundation/umi-bundle-defaults'\n// [/IMPORTS]\n\n// [SETUP]\nconst umi = createUmi('https://api.devnet.solana.com').use(mplBubblegum())\n\nconst assetId = publicKey('YOUR_ASSET_ID')\n// [/SETUP]\n\n// [MAIN]\nconst assetWithProof = await getAssetWithProof(umi, assetId, {\n truncateCanopy: true,\n})\n\n// Leaf / hashing value (65535 when inherited)\nconsole.log(assetWithProof.metadata.sellerFeeBasisPoints)\n\n// Display / payout value from DAS main fields\nconsole.log(assetWithProof.rpcAsset.royalty?.basis_points)\n// [/MAIN]\n\n// [OUTPUT]\n// 65535\n// 500\n// [/OUTPUT]\n" +} + +export const metadata = { + title: "getAssetWithProof with inherited royalties", + description: "Leaf metadata keeps the on-chain sentinel; DAS main royalty fields hold the collection-resolved display rate.", + tags: [], +} + +export const examples = { + umi: { + framework: 'Umi', + language: 'typescript', + code: umiSections.full, + sections: umiSections, + }, + +} diff --git a/src/examples/bubblegum/get-asset-with-proof-inherited/umi.ts b/src/examples/bubblegum/get-asset-with-proof-inherited/umi.ts new file mode 100644 index 000000000..643f13f5c --- /dev/null +++ b/src/examples/bubblegum/get-asset-with-proof-inherited/umi.ts @@ -0,0 +1,28 @@ +// [IMPORTS] +import { getAssetWithProof, mplBubblegum } from '@metaplex-foundation/mpl-bubblegum' +import { publicKey } from '@metaplex-foundation/umi' +import { createUmi } from '@metaplex-foundation/umi-bundle-defaults' +// [/IMPORTS] + +// [SETUP] +const umi = createUmi('https://api.devnet.solana.com').use(mplBubblegum()) + +const assetId = publicKey('YOUR_ASSET_ID') +// [/SETUP] + +// [MAIN] +const assetWithProof = await getAssetWithProof(umi, assetId, { + truncateCanopy: true, +}) + +// Leaf / hashing value (65535 when inherited) +console.log(assetWithProof.metadata.sellerFeeBasisPoints) + +// Display / payout value from DAS main fields +console.log(assetWithProof.rpcAsset.royalty?.basis_points) +// [/MAIN] + +// [OUTPUT] +// 65535 +// 500 +// [/OUTPUT] diff --git a/src/examples/bubblegum/mint-inherit-royalties/index.js b/src/examples/bubblegum/mint-inherit-royalties/index.js new file mode 100644 index 000000000..4136ebc43 --- /dev/null +++ b/src/examples/bubblegum/mint-inherit-royalties/index.js @@ -0,0 +1,32 @@ +/** + * Example: mint-inherit-royalties + * + * + * + * This file is auto-generated by scripts/build-examples.js + * Edit the native .js/.ts and .rs files, then run: node scripts/build-examples.js + */ + +const umiSections = { + "imports": "import { createTreeV2, mintV2, mplBubblegum } from '@metaplex-foundation/mpl-bubblegum'\nimport { createCollection, mplCore, ruleSet } from '@metaplex-foundation/mpl-core'\nimport { generateSigner, some } from '@metaplex-foundation/umi'\nimport { createUmi } from '@metaplex-foundation/umi-bundle-defaults'", + "setup": "const umi = createUmi('https://api.devnet.solana.com')\n .use(mplBubblegum())\n .use(mplCore())\n\nconst merkleTree = generateSigner(umi)\nconst collectionSigner = generateSigner(umi)\n\nawait createTreeV2(umi, {\n merkleTree,\n maxDepth: 5,\n maxBufferSize: 8,\n}).sendAndConfirm(umi)\n\n// The collection must include BubblegumV2 and Royalties plugins.\nawait createCollection(umi, {\n collection: collectionSigner,\n name: 'My Collection',\n uri: 'https://example.com/collection.json',\n plugins: [\n { type: 'BubblegumV2' },\n {\n type: 'Royalties',\n basisPoints: 500, // 5%\n creators: [{ address: umi.identity.publicKey, percentage: 100 }],\n ruleSet: ruleSet('None'),\n },\n ],\n}).sendAndConfirm(umi)", + "main": "// sellerFeeBasisPoints is omitted — the SDK sends the inherit sentinel (65535).\nawait mintV2(umi, {\n collectionAuthority: umi.identity,\n leafOwner: umi.identity.publicKey,\n merkleTree: merkleTree.publicKey,\n coreCollection: collectionSigner.publicKey,\n metadata: {\n name: 'My NFT',\n uri: 'https://example.com/my-nft.json',\n collection: some(collectionSigner.publicKey),\n creators: [], // must be empty when inheriting royalties\n },\n}).sendAndConfirm(umi)", + "output": "// cNFT minted with SELLER_FEE_BASIS_POINTS_INHERIT (65535) on the leaf", + "full": "// [IMPORTS]\nimport { createTreeV2, mintV2, mplBubblegum } from '@metaplex-foundation/mpl-bubblegum'\nimport { createCollection, mplCore, ruleSet } from '@metaplex-foundation/mpl-core'\nimport { generateSigner, some } from '@metaplex-foundation/umi'\nimport { createUmi } from '@metaplex-foundation/umi-bundle-defaults'\n// [/IMPORTS]\n\n// [SETUP]\nconst umi = createUmi('https://api.devnet.solana.com')\n .use(mplBubblegum())\n .use(mplCore())\n\nconst merkleTree = generateSigner(umi)\nconst collectionSigner = generateSigner(umi)\n\nawait createTreeV2(umi, {\n merkleTree,\n maxDepth: 5,\n maxBufferSize: 8,\n}).sendAndConfirm(umi)\n\n// The collection must include BubblegumV2 and Royalties plugins.\nawait createCollection(umi, {\n collection: collectionSigner,\n name: 'My Collection',\n uri: 'https://example.com/collection.json',\n plugins: [\n { type: 'BubblegumV2' },\n {\n type: 'Royalties',\n basisPoints: 500, // 5%\n creators: [{ address: umi.identity.publicKey, percentage: 100 }],\n ruleSet: ruleSet('None'),\n },\n ],\n}).sendAndConfirm(umi)\n// [/SETUP]\n\n// [MAIN]\n// sellerFeeBasisPoints is omitted — the SDK sends the inherit sentinel (65535).\nawait mintV2(umi, {\n collectionAuthority: umi.identity,\n leafOwner: umi.identity.publicKey,\n merkleTree: merkleTree.publicKey,\n coreCollection: collectionSigner.publicKey,\n metadata: {\n name: 'My NFT',\n uri: 'https://example.com/my-nft.json',\n collection: some(collectionSigner.publicKey),\n creators: [], // must be empty when inheriting royalties\n },\n}).sendAndConfirm(umi)\n// [/MAIN]\n\n// [OUTPUT]\n// cNFT minted with SELLER_FEE_BASIS_POINTS_INHERIT (65535) on the leaf\n// [/OUTPUT]\n" +} + +export const metadata = { + title: "mint-inherit-royalties", + description: "", + tags: [], +} + +export const examples = { + umi: { + framework: 'Umi', + language: 'typescript', + code: umiSections.full, + sections: umiSections, + }, + +} diff --git a/src/examples/bubblegum/mint-inherit-royalties/umi.ts b/src/examples/bubblegum/mint-inherit-royalties/umi.ts new file mode 100644 index 000000000..326180d91 --- /dev/null +++ b/src/examples/bubblegum/mint-inherit-royalties/umi.ts @@ -0,0 +1,57 @@ +// [IMPORTS] +import { createTreeV2, mintV2, mplBubblegum } from '@metaplex-foundation/mpl-bubblegum' +import { createCollection, mplCore, ruleSet } from '@metaplex-foundation/mpl-core' +import { generateSigner, some } from '@metaplex-foundation/umi' +import { createUmi } from '@metaplex-foundation/umi-bundle-defaults' +// [/IMPORTS] + +// [SETUP] +const umi = createUmi('https://api.devnet.solana.com') + .use(mplBubblegum()) + .use(mplCore()) + +const merkleTree = generateSigner(umi) +const collectionSigner = generateSigner(umi) + +await createTreeV2(umi, { + merkleTree, + maxDepth: 5, + maxBufferSize: 8, +}).sendAndConfirm(umi) + +// The collection must include BubblegumV2 and Royalties plugins. +await createCollection(umi, { + collection: collectionSigner, + name: 'My Collection', + uri: 'https://example.com/collection.json', + plugins: [ + { type: 'BubblegumV2' }, + { + type: 'Royalties', + basisPoints: 500, // 5% + creators: [{ address: umi.identity.publicKey, percentage: 100 }], + ruleSet: ruleSet('None'), + }, + ], +}).sendAndConfirm(umi) +// [/SETUP] + +// [MAIN] +// sellerFeeBasisPoints is omitted — the SDK sends the inherit sentinel (65535). +await mintV2(umi, { + collectionAuthority: umi.identity, + leafOwner: umi.identity.publicKey, + merkleTree: merkleTree.publicKey, + coreCollection: collectionSigner.publicKey, + metadata: { + name: 'My NFT', + uri: 'https://example.com/my-nft.json', + collection: some(collectionSigner.publicKey), + creators: [], // must be empty when inheriting royalties + }, +}).sendAndConfirm(umi) +// [/MAIN] + +// [OUTPUT] +// cNFT minted with SELLER_FEE_BASIS_POINTS_INHERIT (65535) on the leaf +// [/OUTPUT] diff --git a/src/examples/bubblegum/update-inherit-royalties/index.js b/src/examples/bubblegum/update-inherit-royalties/index.js new file mode 100644 index 000000000..b76adbafc --- /dev/null +++ b/src/examples/bubblegum/update-inherit-royalties/index.js @@ -0,0 +1,32 @@ +/** + * Example: Update away from inherited royalties + * + * Switch a cNFT from inherited seller fees to an explicit rate before removing it from its collection. + * + * This file is auto-generated by scripts/build-examples.js + * Edit the native .js/.ts and .rs files, then run: node scripts/build-examples.js + */ + +const umiSections = { + "imports": "import {\n getAssetWithProof,\n updateMetadataV2,\n UpdateArgsArgs,\n mplBubblegum,\n} from '@metaplex-foundation/mpl-bubblegum'\nimport { publicKey, some } from '@metaplex-foundation/umi'\nimport { createUmi } from '@metaplex-foundation/umi-bundle-defaults'", + "setup": "const umi = createUmi('https://api.devnet.solana.com').use(mplBubblegum())\n\nconst assetId = publicKey('YOUR_ASSET_ID')\nconst collectionPublicKey = publicKey('YOUR_COLLECTION_ADDRESS')", + "main": "const assetWithProof = await getAssetWithProof(umi, assetId, {\n truncateCanopy: true,\n})\n\n// Switch from inherited royalties to an explicit seller fee before removing\n// the cNFT from its collection.\nconst updateArgs: UpdateArgsArgs = {\n sellerFeeBasisPoints: some(550), // explicit 5.5%\n}\n\nawait updateMetadataV2(umi, {\n ...assetWithProof,\n currentMetadata: {\n name: assetWithProof.metadata.name,\n symbol: assetWithProof.metadata.symbol,\n uri: assetWithProof.metadata.uri,\n sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints,\n primarySaleHappened: assetWithProof.metadata.primarySaleHappened,\n isMutable: assetWithProof.metadata.isMutable,\n tokenStandard: assetWithProof.metadata.tokenStandard,\n creators: assetWithProof.metadata.creators,\n collection: some(collectionPublicKey),\n },\n updateArgs,\n coreCollection: collectionPublicKey,\n}).sendAndConfirm(umi)", + "output": "// Leaf seller fee updated from inherit sentinel (65535) to 550 basis points", + "full": "// [IMPORTS]\nimport {\n getAssetWithProof,\n updateMetadataV2,\n UpdateArgsArgs,\n mplBubblegum,\n} from '@metaplex-foundation/mpl-bubblegum'\nimport { publicKey, some } from '@metaplex-foundation/umi'\nimport { createUmi } from '@metaplex-foundation/umi-bundle-defaults'\n// [/IMPORTS]\n\n// [SETUP]\nconst umi = createUmi('https://api.devnet.solana.com').use(mplBubblegum())\n\nconst assetId = publicKey('YOUR_ASSET_ID')\nconst collectionPublicKey = publicKey('YOUR_COLLECTION_ADDRESS')\n// [/SETUP]\n\n// [MAIN]\nconst assetWithProof = await getAssetWithProof(umi, assetId, {\n truncateCanopy: true,\n})\n\n// Switch from inherited royalties to an explicit seller fee before removing\n// the cNFT from its collection.\nconst updateArgs: UpdateArgsArgs = {\n sellerFeeBasisPoints: some(550), // explicit 5.5%\n}\n\nawait updateMetadataV2(umi, {\n ...assetWithProof,\n currentMetadata: {\n name: assetWithProof.metadata.name,\n symbol: assetWithProof.metadata.symbol,\n uri: assetWithProof.metadata.uri,\n sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints,\n primarySaleHappened: assetWithProof.metadata.primarySaleHappened,\n isMutable: assetWithProof.metadata.isMutable,\n tokenStandard: assetWithProof.metadata.tokenStandard,\n creators: assetWithProof.metadata.creators,\n collection: some(collectionPublicKey),\n },\n updateArgs,\n coreCollection: collectionPublicKey,\n}).sendAndConfirm(umi)\n// [/MAIN]\n\n// [OUTPUT]\n// Leaf seller fee updated from inherit sentinel (65535) to 550 basis points\n// [/OUTPUT]\n" +} + +export const metadata = { + title: "Update away from inherited royalties", + description: "Switch a cNFT from inherited seller fees to an explicit rate before removing it from its collection.", + tags: [], +} + +export const examples = { + umi: { + framework: 'Umi', + language: 'typescript', + code: umiSections.full, + sections: umiSections, + }, + +} diff --git a/src/examples/bubblegum/update-inherit-royalties/umi.ts b/src/examples/bubblegum/update-inherit-royalties/umi.ts new file mode 100644 index 000000000..dd390a667 --- /dev/null +++ b/src/examples/bubblegum/update-inherit-royalties/umi.ts @@ -0,0 +1,50 @@ +// [IMPORTS] +import { + getAssetWithProof, + updateMetadataV2, + UpdateArgsArgs, + mplBubblegum, +} from '@metaplex-foundation/mpl-bubblegum' +import { publicKey, some } from '@metaplex-foundation/umi' +import { createUmi } from '@metaplex-foundation/umi-bundle-defaults' +// [/IMPORTS] + +// [SETUP] +const umi = createUmi('https://api.devnet.solana.com').use(mplBubblegum()) + +const assetId = publicKey('YOUR_ASSET_ID') +const collectionPublicKey = publicKey('YOUR_COLLECTION_ADDRESS') +// [/SETUP] + +// [MAIN] +const assetWithProof = await getAssetWithProof(umi, assetId, { + truncateCanopy: true, +}) + +// Switch from inherited royalties to an explicit seller fee before removing +// the cNFT from its collection. +const updateArgs: UpdateArgsArgs = { + sellerFeeBasisPoints: some(550), // explicit 5.5% +} + +await updateMetadataV2(umi, { + ...assetWithProof, + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(collectionPublicKey), + }, + updateArgs, + coreCollection: collectionPublicKey, +}).sendAndConfirm(umi) +// [/MAIN] + +// [OUTPUT] +// Leaf seller fee updated from inherit sentinel (65535) to 550 basis points +// [/OUTPUT] diff --git a/src/pages/en/dev-tools/das-api/methods/get-asset.md b/src/pages/en/dev-tools/das-api/methods/get-asset.md index 0a2a69574..d478953e0 100644 --- a/src/pages/en/dev-tools/das-api/methods/get-asset.md +++ b/src/pages/en/dev-tools/das-api/methods/get-asset.md @@ -7,6 +7,8 @@ tableOfContents: false Returns the information of a compressed/standard asset including metadata and owner. +For Bubblegum V2 cNFTs that inherit seller fees from an MPL-Core collection, collection-resolved display values are on `royalty.basis_points` / `creators`, and leaf values are on `royalty.basis_points_raw` / `creators_raw` (with `royalty.inherited: true`). See [Reading Inherited Royalties](/smart-contracts/bubblegum-v2/reading-inherited-royalties). + ## Parameters | Name | Required | Description | diff --git a/src/pages/en/smart-contracts/bubblegum-v2/collections.md b/src/pages/en/smart-contracts/bubblegum-v2/collections.md index 2f9a4bc3c..316248ea1 100644 --- a/src/pages/en/smart-contracts/bubblegum-v2/collections.md +++ b/src/pages/en/smart-contracts/bubblegum-v2/collections.md @@ -3,7 +3,7 @@ title: Managing Collections metaTitle: Managing Collections - Bubblegum V2 - Metaplex description: Learn how to set, change, and remove MPL-Core collections on compressed NFTs using Bubblegum V2. Covers the setCollectionV2 instruction. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - NFT collection - verify collection @@ -26,6 +26,8 @@ faqs: a: Yes. Use setCollectionV2 with both coreCollection (current) and newCoreCollection (new) parameters. Both collection authorities must sign. - q: What is the BubblegumV2 plugin? a: It is an MPL-Core collection plugin that enables Bubblegum V2 features like freeze/thaw, soulbound cNFTs, and royalty enforcement on the collection. + - q: Can I remove a cNFT from a collection when it inherits royalties? + a: No. Update sellerFeeBasisPoints to an explicit value first, then remove the collection with setCollectionV2. --- ## Summary @@ -118,12 +120,20 @@ const signature = await setCollectionV2(umi, { {% /dialect %} {% /dialect-switcher %} +## Inherited royalties {% #inherited-royalties %} + +cNFTs minted with [inherited seller fee basis points](/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection) store the sentinel value `65535` on the leaf. This affects collection management: + +- **Removing a collection** — `setCollectionV2` rejects the operation while the leaf still uses the inherit sentinel. Update the cNFT to an explicit `sellerFeeBasisPoints` first via [`updateMetadataV2`](/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties). +- **Moving to another collection** — Allowed when the destination collection has the `Royalties` plugin. The cNFT keeps the inherit sentinel and resolves royalties from the new collection. +- **Moving to a collection without royalties** — Rejected with `CollectionMustHaveRoyaltiesPlugin`. ## Notes - The MPL-Core collection must have the `BubblegumV2` plugin enabled before cNFTs can be added to it. - Unlike Bubblegum V1 (which uses Token Metadata collections with a "verified" boolean), V2 uses MPL-Core collections without verification flags. - When changing between collections, both the old and new collection authorities must sign the transaction. +- cNFTs with inherited seller fees cannot be removed from a collection until royalties are set to an explicit value on the leaf. ## FAQ @@ -139,6 +149,10 @@ Yes. Use `setCollectionV2` with both `coreCollection` (current) and `newCoreColl It is an MPL-Core collection plugin that enables Bubblegum V2 features like freeze/thaw, soulbound cNFTs, royalty enforcement, and permanent delegates on the collection level. +### Can I remove a cNFT from a collection when it inherits royalties? + +No. The program returns `CannotRemoveFromCollectionWithInheritedSellerFee`. Use `updateMetadataV2` to set an explicit `sellerFeeBasisPoints` value first, then call `setCollectionV2` to remove the collection. + ## Glossary | Term | Definition | diff --git a/src/pages/en/smart-contracts/bubblegum-v2/faq.md b/src/pages/en/smart-contracts/bubblegum-v2/faq.md index d27549167..a4d99188b 100644 --- a/src/pages/en/smart-contracts/bubblegum-v2/faq.md +++ b/src/pages/en/smart-contracts/bubblegum-v2/faq.md @@ -3,7 +3,7 @@ title: FAQ metaTitle: FAQ - Bubblegum V2 - Metaplex description: Frequently asked questions about Bubblegum V2 compressed NFTs. Covers common issues, costs, transaction size errors, and troubleshooting. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - Bubblegum FAQ - compressed NFT questions @@ -35,6 +35,8 @@ faqs: a: Decompression is only available for Bubblegum V1 assets. V2 does not support decompression. - q: How many cNFTs can I store in one tree? a: The maximum is 2^maxDepth. A depth-30 tree can hold over 1 billion cNFTs, though larger trees cost more in rent. + - q: Can a cNFT inherit royalties from its MPL-Core collection? + a: Yes. Omit sellerFeeBasisPoints when minting to a collection with the Royalties plugin. The leaf stores the inherit sentinel (65535); DAS puts the collection rate on royalty.basis_points and the sentinel on royalty.basis_points_raw. Use getAssetWithProof.metadata (leaf values) for write instructions. --- ## Summary @@ -45,6 +47,7 @@ This page answers the most common questions about Bubblegum V2 compressed NFTs, - Resolve "Transaction too large" errors with `truncateCanopy` or Address Lookup Tables - Understand tree costs and capacity before creating a tree - Bubblegum V2 is not backward-compatible with V1 trees or decompression +- cNFTs can inherit seller fee basis points from an MPL-Core collection's Royalties plugin ## What is Bubblegum V2? @@ -191,3 +194,26 @@ Decompression is only available for Bubblegum V1 assets. Bubblegum V2 does not s ## How many cNFTs can I store in one tree? {% #tree-capacity %} The maximum number of cNFTs is `2^maxDepth`. A depth-14 tree holds 16,384 cNFTs, depth-20 holds ~1 million, depth-24 holds ~16 million, and depth-30 holds over 1 billion. See the [tree capacity table](/smart-contracts/bubblegum-v2/create-trees) for all options. + +## Can a cNFT inherit royalties from its MPL-Core collection? {% #inherited-royalties %} + +Yes. When minting into an MPL-Core collection that has the `Royalties` plugin, you can omit `metadata.sellerFeeBasisPoints` (or pass `SELLER_FEE_BASIS_POINTS_INHERIT`, `65535`). The leaf stores that sentinel on-chain. DAS puts the collection-resolved rate on `royalty.basis_points` / `creators` for display, and the leaf sentinel on `royalty.basis_points_raw` / `creators_raw` (with `royalty.inherited: true`). + +**Requirements:** + +- The collection must have both the `BubblegumV2` and `Royalties` plugins. +- `metadata.creators` must be an empty array when using inherited seller fees. + +**Using `getAssetWithProof`:** + +- **`metadata`** — leaf-canonical values for hashing and write instructions (`sellerFeeBasisPoints` is `65535` when inherited). +- **`rpcAsset`** — use `royalty.basis_points` and `creators` for display / payout UI. + +When calling `updateMetadataV2`, pass leaf metadata as the instruction's `currentMetadata` argument (IDL name for existing leaf state). + +**Collection management:** + +- A cNFT with inherited seller fees **cannot be removed** from its collection until you update to an explicit `sellerFeeBasisPoints`. +- Moving to another collection is allowed when the destination has the `Royalties` plugin. + +See [Reading Inherited Royalties](/smart-contracts/bubblegum-v2/reading-inherited-royalties) for clients reading DAS, [Minting — Inheriting royalties](/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection), [Updating cNFTs](/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties), and [Managing Collections](/smart-contracts/bubblegum-v2/collections#inherited-royalties) for full examples. diff --git a/src/pages/en/smart-contracts/bubblegum-v2/fetch-cnfts.md b/src/pages/en/smart-contracts/bubblegum-v2/fetch-cnfts.md index 06db2e03b..f76acd081 100644 --- a/src/pages/en/smart-contracts/bubblegum-v2/fetch-cnfts.md +++ b/src/pages/en/smart-contracts/bubblegum-v2/fetch-cnfts.md @@ -209,6 +209,7 @@ const rpcAssetList = await umi.rpc.getAssetsByGroup({ - Not all RPC providers support the DAS API. Check the [RPC Providers](/rpc-providers) page for compatible options. - The DAS API plugin is automatically included when you install `mplBubblegum` — no separate installation needed. - Proofs fetched via `getAssetProof` may become stale if the tree is modified. Always fetch fresh proofs before performing write operations. +- For Bubblegum V2 cNFTs that inherit seller fees from a collection, DAS puts the collection rate on `royalty.basis_points` / `creators` and the leaf sentinel on `royalty.basis_points_raw` / `creators_raw`. See [Reading Inherited Royalties](/smart-contracts/bubblegum-v2/reading-inherited-royalties). ## FAQ diff --git a/src/pages/en/smart-contracts/bubblegum-v2/hashed-nft-data.md b/src/pages/en/smart-contracts/bubblegum-v2/hashed-nft-data.md index 354c76b1e..2991ad81b 100644 --- a/src/pages/en/smart-contracts/bubblegum-v2/hashed-nft-data.md +++ b/src/pages/en/smart-contracts/bubblegum-v2/hashed-nft-data.md @@ -3,7 +3,7 @@ title: Hashing NFT Data metaTitle: Hashing NFT Data - Bubblegum V2 - Metaplex description: Learn how compressed NFT data is hashed into merkle tree leaves in Bubblegum V2. Covers MetadataArgsV2, data hash, creator hash, collection hash, and LeafSchemaV2. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - hashed NFT data - merkle leaf @@ -40,7 +40,8 @@ pub struct MetadataArgsV2 { pub symbol: String, /// URI pointing to JSON representing the asset pub uri: String, - /// Royalty basis points that goes to creators in secondary sales (0-10000) + /// Royalty basis points that goes to creators in secondary sales (0-10000), + /// or u16::MAX (65535) to inherit from an MPL-Core collection's Royalties plugin. pub seller_fee_basis_points: u16, /// Immutable, once flipped, all sales of this metadata are considered secondary. pub primary_sale_happened: bool, @@ -55,6 +56,8 @@ pub struct MetadataArgsV2 { } ``` +When `seller_fee_basis_points` is `65535` (`0xffff`, `SELLER_FEE_BASIS_POINTS_INHERIT`), the leaf stores a sentinel instead of a literal royalty percentage. The data hash is computed from this sentinel value, not from the collection's resolved basis points. DAS puts the collection rate on `royalty.basis_points` and the leaf sentinel on `royalty.basis_points_raw`. The JavaScript SDK's `getAssetWithProof` helper puts the leaf sentinel on `metadata.sellerFeeBasisPoints`. See [Reading Inherited Royalties](/smart-contracts/bubblegum-v2/reading-inherited-royalties) and [Inheriting royalties from the collection](/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection). + The cNFT's metadata is hashed multiple times as shown in the diagram and described below: {% diagram %} @@ -283,6 +286,7 @@ Bubblegum operations that involve changing a leaf (`transfer`, `delegate`, `burn | Term | Definition | |------|------------| | **MetadataArgsV2** | The Rust struct containing cNFT metadata (name, symbol, URI, royalties, creators, collection) | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | Sentinel `65535` stored in `seller_fee_basis_points` when royalties are inherited from the MPL-Core collection | | **Data Hash** | keccak-256 hash of the metadata combined with seller_fee_basis_points | | **Creator Hash** | keccak-256 hash of the creator array (address, verified flag, share for each creator) | | **Collection Hash** | keccak-256 hash of the collection public key (new in V2) | diff --git a/src/pages/en/smart-contracts/bubblegum-v2/index.md b/src/pages/en/smart-contracts/bubblegum-v2/index.md index 00394b484..3a26d7f88 100644 --- a/src/pages/en/smart-contracts/bubblegum-v2/index.md +++ b/src/pages/en/smart-contracts/bubblegum-v2/index.md @@ -3,7 +3,7 @@ title: Overview metaTitle: Bubblegum V2 - Compressed NFTs on Solana - Metaplex description: Provides a high-level overview of Bubblegum V2 and compressed NFTs (cNFTs) on Solana. Learn about merkle trees, the DAS API, and new features like freeze, soulbound, and MPL-Core collections. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - compressed NFT - cNFT @@ -84,6 +84,7 @@ Bubblegum V2 builds on the foundation of the original Bubblegum program while in - **Freeze and Thaw Functionality**: Two types of freeze/thaw are available: 1) cNFT owners can delegate freeze authority to a leaf delegate for asset-level control, providing flexibility for various use cases such as preventing transfers during specific events or implementing vesting mechanics. 2) If the `PermanentFreezeDelegate` plugin is enabled on collection creation, project creators can freeze and thaw cNFTs via the permanent freeze delegate for collection-wide control - **MPL-Core Collections Integration**: Bubblegum V2 NFTs can now be added to MPL-Core collections instead of being limited to token metadata collections, allowing for greater flexibility and integration with the broader Metaplex ecosystem. - **Royalty Enforcement**: Since Bubblegum V2 is using [MPL-Core](/smart-contracts/core) Collections, it is possible to enforce royalties on cNFTs e.g. using a `ProgramDenyList`. +- **Inherited Royalties**: cNFTs minted into MPL-Core collections can store a sentinel seller fee basis points value (`65535`) on the leaf and inherit the collection's Royalties plugin configuration instead of duplicating basis points on every mint. - **Soulbound NFTs**: cNFTs can now be made soulbound (non-transferrable), permanently binding them to their owner's wallet. This is perfect for credentials, proof of attendance, identity verification, and more. It requires the `PermanentFreezeDelegate` plugin to be enabled when creating the collection. - **Allow Permanent Transfer**: The permanent transfer delegate can now transfer the cNFT to a new owner without interaction of the leaf owner if the `PermanentTransferDelegate` plugin is enabled on the collection. - **Burning by Authority**: If the Collection has the `PermanentBurnDelegate` plugin enabled, the delegate could burn the NFT without the leaf owner's signature. diff --git a/src/pages/en/smart-contracts/bubblegum-v2/mint-cnfts.md b/src/pages/en/smart-contracts/bubblegum-v2/mint-cnfts.md index c5ef058b8..f3d2fc4a3 100644 --- a/src/pages/en/smart-contracts/bubblegum-v2/mint-cnfts.md +++ b/src/pages/en/smart-contracts/bubblegum-v2/mint-cnfts.md @@ -3,7 +3,7 @@ title: Minting Compressed NFTs metaTitle: Minting Compressed NFTs - Bubblegum V2 - Metaplex description: Learn how to mint compressed NFTs on Bubblegum V2. Covers minting with and without collections, MPL-Core collection setup, and retrieving the asset ID from mint transactions. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - mint compressed NFT - mint cNFT @@ -29,6 +29,8 @@ faqs: a: Only if the tree is set to public. For private trees, only the tree creator or tree delegate can mint. - q: What metadata fields are required for minting? a: The MetadataArgsV2 requires name, uri, sellerFeeBasisPoints, collection (or none), and creators array. + - q: Can a cNFT inherit royalties from its MPL-Core collection? + a: Yes. When minting to a collection with the Royalties plugin, omit sellerFeeBasisPoints (or pass the SELLER_FEE_BASIS_POINTS_INHERIT sentinel). The leaf stores 65535 (0xffff); DAS puts the collection rate on royalty.basis_points and the sentinel on royalty.basis_points_raw. --- ## Summary @@ -39,6 +41,7 @@ faqs: - Mint directly into an MPL-Core collection with the BubblegumV2 plugin - Retrieve the asset ID and leaf schema from the mint transaction - Configure metadata including name, URI, creators, and royalties +- Inherit seller fee basis points from an MPL-Core collection's Royalties plugin In [the previous page](/smart-contracts/bubblegum-v2/create-trees), we saw that we need a Bubblegum Tree to mint Compressed NFTs, and we saw how to create one. Now, let's see how to mint compressed NFTs from a given Bubblegum Tree. {% .lead %} @@ -142,6 +145,28 @@ await createCollection(umi, { {% /dialect %} {% /dialect-switcher %} +## Inheriting royalties from the collection + +When minting to an MPL-Core collection, you can store a **sentinel** seller fee basis points value on the leaf (`65535`, exported as `SELLER_FEE_BASIS_POINTS_INHERIT` / `0xffff`) instead of copying the collection's royalty percentage into every cNFT. DAS puts the collection-resolved rate on `royalty.basis_points` / `creators` for display and the leaf sentinel on `royalty.basis_points_raw` / `creators_raw` (with `royalty.inherited: true`), while the on-chain leaf keeps the sentinel for hashing. + +Clients that **read** DAS responses (wallets, marketplaces, indexers, and apps) should follow [Reading Inherited Royalties](/smart-contracts/bubblegum-v2/reading-inherited-royalties). + +The JavaScript SDK's `mintV2` helper defaults to this behavior when `coreCollection` is provided and `metadata.sellerFeeBasisPoints` is omitted. + +**Requirements:** + +- The MPL-Core collection must have both the `BubblegumV2` and `Royalties` plugins. +- `metadata.creators` must be an **empty array** when using inherited seller fees. Creator splits come from the collection's Royalties plugin instead of leaf-level creators. +- Inherited seller fees are only valid for cNFTs in a collection. Collectionless mints must use an explicit value between `0` and `10000`. + +{% code-tabs-imported from="bubblegum/mint-inherit-royalties" frameworks="umi" /%} + +You can still pass an explicit `sellerFeeBasisPoints` to override the collection default for a single mint. + +{% callout type="note" title="Collection removal" %} +A cNFT with inherited seller fees cannot be removed from its collection until the seller fee is updated to an explicit value. See [Managing Collections](/smart-contracts/bubblegum-v2/collections#inherited-royalties) and [Updating Compressed NFTs](/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties). +{% /callout %} + ### Get Asset ID and Leaf Schema from mint transaction {% #get-leaf-schema-from-mint-transaction %} You can retrieve the leaf and determine the asset ID from the `mintV2` transaction using the `parseLeafFromMintV2Transaction` helper. This function parses the Transaction, therefore you have to make sure that it has been finalized before calling `parseLeafFromMintV2Transaction`. @@ -175,6 +200,7 @@ const assetId = leaf.id; - The Bubblegum Tree must be created before minting. See [Creating Trees](/smart-contracts/bubblegum-v2/create-trees). - For collection mints, the MPL-Core collection must have the `BubblegumV2` plugin enabled. +- To inherit royalties from a collection, the collection must also have the `Royalties` plugin and the leaf's `creators` array must be empty. - The collection authority must sign the transaction when minting to a collection, regardless of whether the tree is public or private. - Use `parseLeafFromMintV2Transaction` only after the transaction is **finalized**, not just confirmed. @@ -194,7 +220,11 @@ Only if the tree was created with `public: true`. For private trees, only the Tr ### What metadata fields are required for minting? -The `MetadataArgsV2` struct requires: `name` (string), `uri` (string pointing to JSON metadata), `sellerFeeBasisPoints` (0-10000), `collection` (public key or none), and `creators` (array of creator objects). +The `MetadataArgsV2` struct requires: `name` (string), `uri` (string pointing to JSON metadata), `sellerFeeBasisPoints` (0-10000, or omit when minting to a collection to inherit from its Royalties plugin), `collection` (public key or none), and `creators` (array of creator objects; must be empty when inheriting royalties). + +### Can a cNFT inherit royalties from its MPL-Core collection? + +Yes. When minting with `coreCollection`, omit `metadata.sellerFeeBasisPoints` and leave `metadata.creators` empty. The SDK stores `SELLER_FEE_BASIS_POINTS_INHERIT` (`65535`) on the leaf. The collection must have the `Royalties` plugin. See [Inheriting royalties from the collection](#inheriting-royalties-from-the-collection). ## Glossary @@ -202,6 +232,7 @@ The `MetadataArgsV2` struct requires: `name` (string), `uri` (string pointing to |------|------------| | **mintV2** | The Bubblegum V2 instruction for minting compressed NFTs, replacing the V1 mint instructions | | **MetadataArgsV2** | The metadata structure passed to mintV2, containing name, URI, royalties, collection, and creators | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | Sentinel value `65535` (`0xffff`) stored on-chain to indicate royalties are inherited from the MPL-Core collection | | **Collection Authority** | The signer authorized to manage the MPL-Core collection — required when minting to a collection | | **BubblegumV2 Plugin** | An MPL-Core collection plugin that enables Bubblegum V2 features (freeze, soulbound, royalties) | | **Asset ID** | A PDA derived from the merkle tree address and leaf index, uniquely identifying a compressed NFT | diff --git a/src/pages/en/smart-contracts/bubblegum-v2/reading-inherited-royalties.md b/src/pages/en/smart-contracts/bubblegum-v2/reading-inherited-royalties.md new file mode 100644 index 000000000..4f3a107a2 --- /dev/null +++ b/src/pages/en/smart-contracts/bubblegum-v2/reading-inherited-royalties.md @@ -0,0 +1,164 @@ +--- +title: Reading Inherited Royalties +metaTitle: Reading Inherited Royalties - Bubblegum V2 - Metaplex +description: How wallets, marketplaces, indexers, and other clients should read DAS getAsset responses for Bubblegum V2 cNFTs that inherit seller fees from an MPL-Core collection. +created: '07-16-2026' +updated: '08-06-2026' +keywords: + - inherited royalties + - seller fee basis points + - DAS API + - getAsset + - basis_points_raw + - creators_raw + - inherited + - Bubblegum V2 +about: + - Compressed NFTs + - DAS API + - Royalties +proficiencyLevel: Intermediate +programmingLanguage: + - JavaScript + - TypeScript +faqs: + - q: Why does royalty.basis_points_raw show 65535? + a: That is the on-chain inherit sentinel used for leaf hashing. royalty.basis_points already holds the collection rate for display. + - q: Why is creators_raw empty on an inherited cNFT? + a: Leaf creators must be empty when SFBP is inherited. Use creators for collection royalty payees. + - q: Do I need to change anything for non-inherited cNFTs? + a: No. When inheritance is not used, the _raw fields and inherited are omitted and the main royalty and creators fields behave as before. +--- + +## Summary + +Bubblegum V2 can store seller fees as an **inherit sentinel** (`65535`) on the leaf and resolve the effective rate from the MPL-Core collection's Royalties plugin. DAS puts **collection-resolved values on the main fields** (for display) and exposes leaf values on `_raw` fields (for hashing). + +- Use **main fields** (`royalty.basis_points`, `creators`) for royalty UI and payout display +- Use **`_raw` fields** (`royalty.basis_points_raw`, `creators_raw`) for proofs, hashing, and write instructions +- Non-inherited assets are unchanged — `_raw` / `inherited` are omitted + +This page is for **any client that reads** `getAsset` / DAS responses — wallets, marketplaces, indexers, analytics, and apps. For minting and updating inherited cNFTs, see [Minting](/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection) and [Updating](/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties). + +## When it applies + +A cNFT is using inherited royalties when: + +- It is a Bubblegum V2 asset in an MPL-Core collection with the `Royalties` plugin, and +- The leaf seller fee is the inherit sentinel `65535` (`0xffff`) + +DAS signals this with `royalty.inherited: true` and `royalty.basis_points_raw: 65535` when the collection royalty can be resolved onto the main fields. + +## Field map + +| Use case | Fields | +|----------|--------| +| Display rate / royalty UI | `royalty.basis_points`, `royalty.percent` | +| Display payees / payout splits | `creators` | +| Hashing, merkle proofs, write instructions | `royalty.basis_points_raw`, `creators_raw` | +| Detect inherit mode | `royalty.inherited` (or `basis_points_raw === 65535`) | + +### Example DAS response (inherited) + +```json +"royalty": { + "royalty_model": "creators", + "target": null, + "percent": 0.075, + "basis_points": 750, + "basis_points_raw": 65535, + "inherited": true, + "primary_sale_happened": false, + "locked": false +}, +"creators": [ + { + "address": "CJkzXwVwqiaSvMuRb3obrZHdrPFjCMBJBDrjspn72tDv", + "share": 100, + "verified": true + } +], +"creators_raw": [] +``` + +- `basis_points: 750` is the collection rate to show users (7.5%). +- `basis_points_raw: 65535` is the on-chain sentinel used in the leaf data hash — **not** a 655.35% royalty. +- `creators` are collection Royalties plugin payees; `creators_raw: []` is the leaf creators array for hashing. + +If the collection cannot be resolved, `basis_points` may fall back while `basis_points_raw` remains `65535`. + +## Detection and display helpers + +```ts +const INHERIT = 0xffff // 65535 + +function isInheritedRoyalty(royalty: { + basis_points: number + basis_points_raw?: number | null + inherited?: boolean | null +}): boolean { + return ( + royalty.inherited === true || + royalty.basis_points_raw === INHERIT + ) +} + +function leafBasisPoints(royalty: { + basis_points: number + basis_points_raw?: number | null + inherited?: boolean | null +}): number { + if (royalty.basis_points_raw != null) return royalty.basis_points_raw + if (royalty.inherited) return INHERIT + return royalty.basis_points +} + +function leafCreators(asset: { + creators: Array<{ address: string; share: number; verified: boolean }> + creators_raw?: Array<{ + address: string + share: number + verified: boolean + }> | null +}) { + return asset.creators_raw ?? asset.creators +} +``` + +With `@metaplex-foundation/digital-asset-standard-api`: + +```ts +import { + SELLER_FEE_BASIS_POINTS_INHERIT, + isInheritedSfbpRoyalty, + getRawSellerFeeBasisPoints, + getResolvedSellerFeeBasisPoints, +} from '@metaplex-foundation/digital-asset-standard-api' + +const royalty = asset.royalty +if (isInheritedSfbpRoyalty(royalty)) { + const rate = getResolvedSellerFeeBasisPoints(royalty) // e.g. 750 (display) + const leaf = getRawSellerFeeBasisPoints(royalty) // 65535 + const payees = asset.creators // collection payees + const leafCreators = asset.creators_raw ?? [] +} +``` + +## What not to do + +- Do **not** show `65535` or `6.5535%` as the user-facing royalty rate — that value lives on `basis_points_raw`. +- Do **not** assume empty `creators_raw` means no royalty recipients; display payees are on `creators`. +- Do **not** use main `basis_points` / `creators` when recomputing leaf hashes or building Bubblegum write instructions — use `basis_points_raw` and `creators_raw`. + +## Bubblegum SDK note + +`getAssetWithProof` builds `metadata` from DAS **leaf** fields (`basis_points_raw`, `creators_raw`) so write instructions hash correctly. For UI rates after `getAssetWithProof`, read `rpcAsset.royalty.basis_points` and `rpcAsset.creators`. See the [JavaScript SDK](/smart-contracts/bubblegum-v2/sdk/javascript#getassetwithproof-and-inherited-royalties). + +## Related + +- [Fetching Compressed NFTs](/smart-contracts/bubblegum-v2/fetch-cnfts) +- [Minting — Inheriting royalties](/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection) +- [Updating cNFTs — Inherited royalties](/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties) +- [Hashing NFT Data](/smart-contracts/bubblegum-v2/hashed-nft-data) +- [DAS getAsset](/dev-tools/das-api/methods/get-asset) +- [FAQ — Inherited royalties](/smart-contracts/bubblegum-v2/faq#inherited-royalties) diff --git a/src/pages/en/smart-contracts/bubblegum-v2/sdk/javascript.md b/src/pages/en/smart-contracts/bubblegum-v2/sdk/javascript.md index 354dd38a3..0e75db0c0 100644 --- a/src/pages/en/smart-contracts/bubblegum-v2/sdk/javascript.md +++ b/src/pages/en/smart-contracts/bubblegum-v2/sdk/javascript.md @@ -3,7 +3,7 @@ title: JavaScript SDK metaTitle: JavaScript SDK - Bubblegum V2 - Metaplex description: Complete reference for the Metaplex Bubblegum V2 JavaScript SDK. Covers Umi setup, creating trees, minting, transferring, burning, updating, delegating, freezing, and fetching compressed NFTs. created: '01-15-2025' -updated: '02-25-2026' +updated: '06-19-2026' keywords: - mpl-bubblegum JavaScript - Bubblegum V2 TypeScript SDK @@ -39,7 +39,7 @@ faqs: - q: Can I use this SDK with Bubblegum V1 trees? a: No. This SDK targets Bubblegum V2 and uses LeafSchemaV2. Use the legacy Bubblegum SDK for V1 trees. - q: What is getAssetWithProof and why do I need it? - a: getAssetWithProof is a helper that fetches all parameters needed for leaf-mutating instructions (proof, root, leaf index, nonce, metadata) from the DAS API in one call. Almost every write instruction requires it. + a: getAssetWithProof is a helper that fetches all parameters needed for leaf-mutating instructions (proof, root, leaf index, nonce, metadata) from the DAS API in one call. For inherited royalties, metadata.sellerFeeBasisPoints is the on-chain leaf sentinel (65535); resolved collection rates are on rpcAsset.royalty.basis_points. --- The **Bubblegum V2 JavaScript SDK** (`@metaplex-foundation/mpl-bubblegum`) is the recommended TypeScript/JavaScript library for creating and managing [compressed NFTs](/smart-contracts/bubblegum-v2) on Solana. Built on the [Umi framework](/dev-tools/umi), it provides type-safe functions for all Bubblegum V2 operations and includes the [DAS API](/smart-contracts/bubblegum-v2/fetch-cnfts) plugin automatically. {% .lead %} @@ -196,6 +196,14 @@ await mintV2(umi, { }).sendAndConfirm(umi) ``` +### Inherit royalties from the collection + +When `coreCollection` is set, the SDK's `mintV2` helper defaults to inherited royalties if `metadata.sellerFeeBasisPoints` is omitted. The leaf stores `SELLER_FEE_BASIS_POINTS_INHERIT` (`65535`). The collection must have the `Royalties` plugin and `metadata.creators` must be empty. + +{% code-tabs-imported from="bubblegum/mint-inherit-royalties" frameworks="umi" /%} + +See [Minting Compressed NFTs — Inheriting royalties](/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection) for collection setup and constraints. + ### Get Asset ID After Minting Use `parseLeafFromMintV2Transaction` to retrieve the leaf schema (including the asset ID) after a mint confirms. @@ -275,13 +283,25 @@ const updateArgs: UpdateArgsArgs = { await updateMetadataV2(umi, { ...assetWithProof, leafOwner: assetWithProof.leafOwner, - currentMetadata: assetWithProof.metadata, + // Instruction arg name for existing leaf metadata (V2 collection is a pubkey). + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(publicKey('YourCollectionAddressHere')), + }, updateArgs, - // If cNFT belongs to a collection, pass the collection address: coreCollection: publicKey('YourCollectionAddressHere'), }).sendAndConfirm(umi) ``` +`getAssetWithProof.metadata` always mirrors the leaf (including `65535` when royalties are inherited). For display, read `rpcAsset.royalty.basis_points` and `rpcAsset.creators`. + ## Delegate a Compressed NFT A [leaf delegate](/smart-contracts/bubblegum-v2/delegate-cnfts) can transfer, burn, and freeze a cNFT on the owner's behalf. The delegate resets to the new owner after any transfer. @@ -483,6 +503,21 @@ await unverifyCreatorV2(umi, { The DAS API plugin is automatically registered by `mplBubblegum()`. See [Fetch cNFTs](/smart-contracts/bubblegum-v2/fetch-cnfts) for the full breakdown of available methods. +### getAssetWithProof and inherited royalties {% #getassetwithproof-and-inherited-royalties %} + +`getAssetWithProof` combines `getAsset` and `getAssetProof` into the parameter shape expected by write instructions. + +| Field | Purpose | +|-------|---------| +| `metadata` | Leaf-canonical metadata for hashing and write instructions (from `basis_points_raw` / `creators_raw`). When royalties are inherited, `sellerFeeBasisPoints` is `65535` and `creators` is the leaf creator list (usually empty). | +| `rpcAsset` | Full DAS response. Collection-resolved display values live on `royalty.basis_points`, `royalty.percent`, and `creators`; leaf values are on `royalty.basis_points_raw` and `creators_raw`. | + +`updateMetadataV2` still names its existing-leaf argument `currentMetadata` (IDL). Build that `MetadataArgsV2` from `assetWithProof.metadata` leaf fields, with V2 `collection` as a pubkey. + +Clients reading DAS directly should follow [Reading Inherited Royalties](/smart-contracts/bubblegum-v2/reading-inherited-royalties). + +{% code-tabs-imported from="bubblegum/get-asset-with-proof-inherited" frameworks="umi" /%} + ### Fetch a Single cNFT ```ts {% title="fetch-asset.ts" %} @@ -605,7 +640,8 @@ Your RPC provider may not support the Metaplex DAS API. Switch to a [compatible | `setNonTransferableV2` | Make a cNFT permanently soulbound (irreversible) | | `verifyCreatorV2` | Set verified flag on a creator entry | | `unverifyCreatorV2` | Remove verified flag from a creator entry | -| `getAssetWithProof` | Fetch all proof parameters needed for write instructions | +| `getAssetWithProof` | Fetch proof parameters; `metadata` is leaf-canonical, display inheritance is on `rpcAsset` | +| `SELLER_FEE_BASIS_POINTS_INHERIT` | Sentinel constant (`65535`) for royalties inherited from an MPL-Core collection | | `findLeafAssetIdPda` | Derive a cNFT asset ID from tree address and leaf index | | `parseLeafFromMintV2Transaction` | Extract leaf schema (including asset ID) from a mint transaction | diff --git a/src/pages/en/smart-contracts/bubblegum-v2/update-cnfts.md b/src/pages/en/smart-contracts/bubblegum-v2/update-cnfts.md index 00b9391d3..12a986a5d 100644 --- a/src/pages/en/smart-contracts/bubblegum-v2/update-cnfts.md +++ b/src/pages/en/smart-contracts/bubblegum-v2/update-cnfts.md @@ -3,7 +3,7 @@ title: Updating Compressed NFTs metaTitle: Updating Compressed NFTs - Bubblegum V2 - Metaplex description: Learn how to update compressed NFT metadata using Bubblegum V2. Covers update authority for collection-based and tree-based cNFTs. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - update compressed NFT - update cNFT @@ -24,6 +24,8 @@ faqs: a: You can update the name, URI, seller fee basis points, and other metadata fields defined in UpdateArgsArgs. Use some('newValue') for fields you want to change. - q: Do I need to pass the collection when updating? a: Yes, if the cNFT belongs to a collection. Pass the coreCollection parameter with the collection's public key. The collection authority must sign the transaction. + - q: How do I update a cNFT that inherits royalties from its collection? + a: Pass leaf metadata from getAssetWithProof as updateMetadataV2's currentMetadata arg (IDL name for existing leaf state). sellerFeeBasisPoints is the on-chain sentinel when royalties are inherited. --- ## Summary @@ -34,6 +36,7 @@ faqs: - Collection authority updates cNFTs that belong to a collection - Tree authority updates cNFTs that do not belong to a collection - Changes are reflected in the merkle tree and indexed by DAS API providers +- Use leaf metadata from `getAssetWithProof` as `updateMetadataV2`'s `currentMetadata` arg (IDL name for existing leaf state) The **updateMetadataV2** instruction can be used to modify the metadata of a Compressed NFT. The Merkle root is updated to reflect the propagated hash of the data, and RPC providers who conform to the [Metaplex DAS API](https://github.com/metaplex-foundation/digital-asset-standard-api) will update their index of the cNFTs. @@ -90,7 +93,17 @@ const updateArgs: UpdateArgsArgs = { await updateMetadataV2(umi, { ...assetWithProof, leafOwner, - currentMetadata: assetWithProof.metadata, + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(publicKey('22222222222222222222222222222222')), + }, updateArgs, // Optional param. If your authority is a different signer type // than the current umi identity assign that signer here. @@ -100,6 +113,22 @@ await updateMetadataV2(umi, { }).sendAndConfirm(umi) ``` +{% callout type="note" title="Leaf metadata for write instructions" %} +`getAssetWithProof.metadata` is always leaf-canonical — including `sellerFeeBasisPoints: 65535` when royalties are inherited. Collection-resolved display values are on `rpcAsset.royalty.basis_points` and `rpcAsset.creators`. + +`updateMetadataV2`'s `currentMetadata` argument is the IDL name for existing leaf metadata (V2 shape: `collection` is a pubkey). Build it from `assetWithProof.metadata`. + +For guidance on DAS response fields when reading assets, see [Reading Inherited Royalties](/smart-contracts/bubblegum-v2/reading-inherited-royalties). +{% /callout %} + +## Inherited royalties {% #inherited-royalties %} + +You can switch a cNFT **to** inherited royalties by setting `updateArgs.sellerFeeBasisPoints` to `some(SELLER_FEE_BASIS_POINTS_INHERIT)`. The collection must have the `Royalties` plugin and the updated metadata must have an empty `creators` array. + +To switch **from** inherited royalties back to an explicit percentage — for example before [removing the cNFT from its collection](/smart-contracts/bubblegum-v2/collections#inherited-royalties) — pass the desired basis points: + +{% code-tabs-imported from="bubblegum/update-inherit-royalties" frameworks="umi" /%} + {% /totem %} {% /dialect %} {% /dialect-switcher %} @@ -108,8 +137,9 @@ await updateMetadataV2(umi, { ## Notes - The update authority depends on whether the cNFT belongs to a collection. Collection cNFTs use the collection authority; standalone cNFTs use the tree authority. -- You must pass `currentMetadata` from `getAssetWithProof` so the program can verify the current leaf before applying updates. +- Pass leaf metadata from `getAssetWithProof` as `updateMetadataV2`'s `currentMetadata` arg so the program can verify the current leaf before applying updates. - Use `some()` for fields to update; omit fields you wish to leave unchanged. +- Inherited seller fees require an empty leaf-level `creators` array and a collection with the `Royalties` plugin. ## FAQ @@ -125,6 +155,10 @@ You can update the name, URI, seller fee basis points, and other metadata fields Yes, if the cNFT belongs to a collection. Pass the `coreCollection` parameter with the collection's public key. The collection authority must sign the transaction. +### How do I update a cNFT that inherits royalties from its collection? + +Pass leaf metadata from `getAssetWithProof` as `updateMetadataV2`'s `currentMetadata` arg so the on-chain sentinel is used for verification. Use `updateArgs.sellerFeeBasisPoints` with `some(SELLER_FEE_BASIS_POINTS_INHERIT)` to switch to inherited royalties, or an explicit number to switch away from them. + ## Glossary | Term | Definition | @@ -133,4 +167,5 @@ Yes, if the cNFT belongs to a collection. Pass the `coreCollection` parameter wi | **Collection Authority** | The update authority of the MPL-Core collection, authorized to update cNFTs in that collection | | **Tree Authority** | The tree creator or delegate, authorized to update cNFTs that do not belong to a collection | | **UpdateArgsArgs** | The TypeScript type defining which metadata fields to update, using Option wrappers | -| **currentMetadata** | The existing metadata of the cNFT, fetched via getAssetWithProof and required for verification | +| **currentMetadata** | IDL argument on `updateMetadataV2` for existing leaf metadata; build it from `getAssetWithProof.metadata` | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | Sentinel value `65535` indicating royalties are inherited from the MPL-Core collection | diff --git a/src/pages/ja/dev-tools/das-api/methods/get-asset.md b/src/pages/ja/dev-tools/das-api/methods/get-asset.md index bcbcaf251..2a123162b 100644 --- a/src/pages/ja/dev-tools/das-api/methods/get-asset.md +++ b/src/pages/ja/dev-tools/das-api/methods/get-asset.md @@ -7,6 +7,8 @@ tableOfContents: false メタデータとオーナーを含む圧縮/標準アセットの情報を返します。 +MPL-Coreコレクションから販売者手数料を継承するBubblegum V2 cNFTでは、コレクションから解決された表示値は `royalty.basis_points` / `creators` にあり、リーフ値は `royalty.basis_points_raw` / `creators_raw` にあります（`royalty.inherited: true`）。[継承ロイヤリティの読み取り](/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties)を参照してください。 + ## パラメーター | 名前 | 必須 | 説明 | diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/collections.md b/src/pages/ja/smart-contracts/bubblegum-v2/collections.md index 12ebecad9..6334a969c 100644 --- a/src/pages/ja/smart-contracts/bubblegum-v2/collections.md +++ b/src/pages/ja/smart-contracts/bubblegum-v2/collections.md @@ -3,7 +3,7 @@ title: コレクションの管理 metaTitle: コレクションの管理 - Bubblegum V2 description: Bubblegumでコレクションの設定、検証、検証解除を行う方法を学びます。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - NFT collection - verify collection @@ -26,6 +26,8 @@ faqs: a: はい。coreCollection（現在）とnewCoreCollection（新規）の両方のパラメータを指定してsetCollectionV2を使用します。両方のコレクション権限が署名する必要があります。 - q: BubblegumV2プラグインとは何ですか？ a: コレクション上でフリーズ/解凍、ソウルバウンドcNFT、ロイヤリティ強制などのBubblegum V2機能を有効にするMPL-Coreコレクションプラグインです。 + - q: ロイヤリティを継承しているcNFTをコレクションから削除できますか？ + a: いいえ。まずsellerFeeBasisPointsを明示的な値に更新してから、setCollectionV2でコレクションを削除してください。 --- ## Summary @@ -118,15 +120,38 @@ const signature = await setCollectionV2(umi, { {% /dialect %} {% /dialect-switcher %} +## 継承されたロイヤリティ {% #inherited-royalties %} + +[コレクションからセラーフィーベーシスポイントを継承](/ja/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)してミントされたcNFTは、リーフにセンチネル値 `65535` を保存します。これはコレクション管理に影響します： + +- **コレクションの削除** — リーフがまだ継承センチネルを使用している間、`setCollectionV2` は操作を拒否します。まず [`updateMetadataV2`](/ja/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties) でcNFTの `sellerFeeBasisPoints` を明示的な値に更新してください。 +- **別のコレクションへの移動** — 移行先コレクションに `Royalties` プラグインがある場合は許可されます。cNFTは継承センチネルを保持し、新しいコレクションからロイヤリティを解決します。 +- **ロイヤリティのないコレクションへの移動** — `CollectionMustHaveRoyaltiesPlugin` で拒否されます。 + ## Notes - The MPL-Core collection must have the `BubblegumV2` plugin enabled before cNFTs can be added to it. - Unlike Bubblegum V1 (which uses Token Metadata collections with a "verified" boolean), V2 uses MPL-Core collections without verification flags. - When changing between collections, both the old and new collection authorities must sign the transaction. +- 継承されたセラーフィーを持つcNFTは、リーフでロイヤリティが明示的な値に設定されるまでコレクションから削除できません。 ## FAQ -# +### ミント後にcNFTをコレクションに追加するにはどうすればよいですか？ + +`newCoreCollection` パラメータをコレクションの公開鍵に設定して `setCollectionV2` 命令を使用します。コレクション権限が署名する必要があります。 + +### cNFTのコレクションを変更できますか？ + +はい。`coreCollection`（現在）と `newCoreCollection`（新規）の両方を指定して `setCollectionV2` を使用します。権限が異なるアカウントの場合、両方のコレクション権限が署名する必要があります。 + +### BubblegumV2プラグインとは何ですか？ + +フリーズ/解凍、ソウルバウンドcNFT、ロイヤリティ強制、コレクションレベルのパーマネントデリゲートなど、Bubblegum V2機能を有効にするMPL-Coreコレクションプラグインです。 + +### ロイヤリティを継承しているcNFTをコレクションから削除できますか？ + +いいえ。プログラムは `CannotRemoveFromCollectionWithInheritedSellerFee` を返します。まず `updateMetadataV2` で `sellerFeeBasisPoints` を明示的な値に設定し、その後 `setCollectionV2` を呼び出してコレクションを削除してください。 ## Glossary diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/faq.md b/src/pages/ja/smart-contracts/bubblegum-v2/faq.md index 2db1bf374..b5dee3806 100644 --- a/src/pages/ja/smart-contracts/bubblegum-v2/faq.md +++ b/src/pages/ja/smart-contracts/bubblegum-v2/faq.md @@ -3,7 +3,7 @@ title: FAQ metaTitle: FAQ - Bubblegum V2 description: Bubblegumに関するよくある質問。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - Bubblegum FAQ - compressed NFT questions @@ -35,6 +35,8 @@ faqs: a: 解凍はBubblegum V1アセットのみで利用できます。V2は解凍をサポートしていません。 - q: 1つのツリーにcNFTをいくつ保存できますか？ a: 最大数は2^maxDepthです。深度30のツリーは10億を超えるcNFTを保持できますが、大きなツリーほどレントのコストが高くなります。 + - q: cNFTはMPL-Coreコレクションからロイヤリティを継承できますか？ + a: はい。Royaltiesプラグインを持つコレクションにミントする場合、sellerFeeBasisPointsを省略します。リーフには継承センチネル（65535）が保存され、DASはroyalty.basis_pointsにコレクション料率を、royalty.basis_points_rawにセンチネルを置きます。書き込み命令にはgetAssetWithProof.metadata（リーフ値）を使用してください。 --- ## Summary @@ -45,6 +47,7 @@ faqs: - `truncateCanopy`またはアドレスルックアップテーブルで「トランザクションが大きすぎる」エラーを解決する - ツリーを作成する前にツリーのコストと容量を理解する - Bubblegum V2はV1ツリーや圧縮解除との後方互換性はない +- cNFTはMPL-CoreコレクションのRoyaltiesプラグインからセラーフィーベーシスポイントを継承できる ## Bubblegum V2とは何ですか？ @@ -87,7 +90,7 @@ Bubblegum UmiライブラリはPATHの説明に適合する`getAssetWithProof` キャノピーサイズによっては、`getAssetWithProof`ヘルパーの`truncateCanopy: true`パラメータを使用することが意味がある場合があります。これによりツリー設定を取得し、不要な証明を切り捨てます。これはトランザクションサイズが大きくなりすぎる場合に役立ちます。 ```ts -import { getAssetWithProof, transfer } from '@metaplex-foundation/mpl-bubblegum' +import { getAssetWithProof, transferV2 } from '@metaplex-foundation/mpl-bubblegum' const assetWithProof = await getAssetWithProof(umi, assetId, // { truncateCanopy: true } // 証明を剪定するためのオプション @@ -97,6 +100,81 @@ await transferV2(umi, { leafOwner: leafOwnerA, // 署名者として。 newLeafOwner: leafOwnerB.publicKey, }).sendAndConfirm(umi); +``` + +{% totem-accordion title="ヘルパー関数なしでパラメータを取得" %} + +完成度のために、提供されたヘルパー関数を使用せずに同じ結果を得る方法は次のとおりです。 + +```ts +import { publicKeyBytes } from '@metaplex-foundation/umi' +import { transferV2 } from '@metaplex-foundation/mpl-bubblegum' + +const rpcAsset = await umi.rpc.getAsset(assetId) +const rpcAssetProof = await umi.rpc.getAssetProof(assetId) await transferV2(umi, { - ...assetWithProof, + leafOwner: leafOwnerA, + newLeafOwner: leafOwnerB.publicKey, + merkleTree: rpcAssetProof.tree_id, + root: publicKeyBytes(rpcAssetProof.root), + dataHash: publicKeyBytes(rpcAsset.compression.data_hash), + creatorHash: publicKeyBytes(rpcAsset.compression.creator_hash), + nonce: rpcAsset.compression.leaf_id, + index: rpcAssetProof.node_index - 2 ** rpcAssetProof.proof.length, + proof: rpcAssetProof.proof, +}).sendAndConfirm(umi) +``` + +{% /totem-accordion %} + +{% /totem %} +{% /dialect %} +{% /dialect-switcher %} + +## 「トランザクションが大きすぎる」エラーを解決する方法 {% #transaction-size %} + +転送やバーンなどのリーフ置換操作を行う際、「トランザクションが大きすぎる」エラーが発生することがあります。解決するには次の方法を検討してください： + +1. `truncateCanopy` オプションを使用する： + `getAssetWithProof` 関数に `{ truncateCanopy: true }` を渡します： + + ```ts + const assetWithProof = await getAssetWithProof(umi, assetId, + { truncateCanopy: true } + ); + ``` + + このオプションはマークルツリー設定を取得し、キャノピーに基づいて不要な証明を削除して `assetWithProof` を最適化します。追加のRPC呼び出しが発生しますが、トランザクションサイズを大幅に削減します。 + +2. バージョン管理トランザクションとアドレスルックアップテーブルを使用する： + 別のアプローチとして、[バージョン管理トランザクションとアドレスルックアップテーブル](/ja/dev-tools/umi/toolbox/address-lookup-table)を実装できます。 + +これらの手法を適用することで、トランザクションサイズ制限を克服し、操作を正常に実行できます。 + +## 1つのツリーにcNFTをいくつ保存できますか？ {% #tree-capacity %} + +cNFTの最大数は `2^maxDepth` です。深度14のツリーは16,384個、深度20は約100万個、深度24は約1,600万個、深度30は10億を超えるcNFTを保持できます。すべてのオプションについては[ツリー容量表](/ja/smart-contracts/bubblegum-v2/create-trees)を参照してください。 + +## cNFTはMPL-Coreコレクションからロイヤリティを継承できますか？ {% #inherited-royalties %} + +はい。`Royalties` プラグインを持つMPL-Coreコレクションにミントする場合、`metadata.sellerFeeBasisPoints` を省略（または `SELLER_FEE_BASIS_POINTS_INHERIT`、`65535` を渡す）できます。リーフにはそのセンチネルがオンチェーンに保存されます。DASは表示用に `royalty.basis_points` / `creators` にコレクションから解決された料率を置き、`royalty.basis_points_raw` / `creators_raw` にリーフセンチネルを置きます（`royalty.inherited: true`）。 + +**要件:** + +- コレクションには `BubblegumV2` と `Royalties` の両方のプラグインが必要です。 +- 継承されたセラーフィーを使用する場合、`metadata.creators` は空の配列である必要があります。 + +**`getAssetWithProof` の使用:** + +- **`metadata`** — ハッシュと書き込み命令用のリーフ正規値（継承時は `sellerFeeBasisPoints` が `65535`）。 +- **`rpcAsset`** — 表示 / 支払いUIには `royalty.basis_points` と `creators` を使用してください。 + +`updateMetadataV2` を呼び出すときは、リーフメタデータを命令の `currentMetadata` 引数（既存リーフ状態のIDL名）として渡してください。 + +**コレクション管理:** + +- 継承されたセラーフィーを持つcNFTは、明示的な `sellerFeeBasisPoints` に更新するまでコレクションから**削除できません**。 +- 移行先に `Royalties` プラグインがある場合、別のコレクションへの移動は許可されます。 + +DASを読むクライアントは[継承ロイヤリティの読み取り](/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties)を参照し、詳細な例については[ミント — ロイヤリティの継承](/ja/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)、[cNFTの更新](/ja/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)、[コレクションの管理](/ja/smart-contracts/bubblegum-v2/collections#inherited-royalties)を参照してください。 diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/fetch-cnfts.md b/src/pages/ja/smart-contracts/bubblegum-v2/fetch-cnfts.md index ec263348b..50c6805de 100644 --- a/src/pages/ja/smart-contracts/bubblegum-v2/fetch-cnfts.md +++ b/src/pages/ja/smart-contracts/bubblegum-v2/fetch-cnfts.md @@ -78,6 +78,7 @@ umi.use(dasApi()); - Not all RPC providers support the DAS API. Check the [RPC Providers](/rpc-providers) page for compatible options. - The DAS API plugin is automatically included when you install `mplBubblegum` — no separate installation needed. - Proofs fetched via `getAssetProof` may become stale if the tree is modified. Always fetch fresh proofs before performing write operations. +- コレクションから販売者手数料を継承するBubblegum V2 cNFTでは、DASは `royalty.basis_points` / `creators` にコレクション料率を、`royalty.basis_points_raw` / `creators_raw` にリーフセンチネルを置きます。[継承ロイヤリティの読み取り](/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties)を参照してください。 ## FAQ diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/hashed-nft-data.md b/src/pages/ja/smart-contracts/bubblegum-v2/hashed-nft-data.md index b78324fe6..f2a9c6cc5 100644 --- a/src/pages/ja/smart-contracts/bubblegum-v2/hashed-nft-data.md +++ b/src/pages/ja/smart-contracts/bubblegum-v2/hashed-nft-data.md @@ -3,7 +3,7 @@ title: NFTデータのハッシュ化 metaTitle: NFTデータのハッシュ化 - Bubblegum V2 description: BubblegumでNFTデータがどのようにハッシュ化されるかについて詳しく学びます。 created: '2025-01-15' -updated: '2026-02-24' +updated: '06-19-2026' keywords: - hashed NFT data - merkle leaf @@ -40,7 +40,8 @@ pub struct MetadataArgsV2 { pub symbol: String, /// アセットを表すJSONを指すURI pub uri: String, - /// 二次販売で作成者に行くロイヤリティベーシスポイント（0-10000） + /// 二次販売で作成者に行くロイヤリティベーシスポイント（0-10000）、 + /// または MPL-Core コレクションの Royalties プラグインから継承する場合は u16::MAX（65535）。 pub seller_fee_basis_points: u16, /// 不変、一度変更されると、このメタデータのすべての販売は二次とみなされる。 pub primary_sale_happened: bool, @@ -55,6 +56,8 @@ pub struct MetadataArgsV2 { } ``` +`seller_fee_basis_points` が `65535`（`0xffff`、`SELLER_FEE_BASIS_POINTS_INHERIT`）の場合、リーフにはリテラルなロイヤリティ率ではなくセンチネルが保存されます。データハッシュはコレクションの解決済みベーシスポイントではなく、このセンチネル値から計算されます。DASは `royalty.basis_points` にコレクション料率を、`royalty.basis_points_raw` にリーフセンチネルを置きます。JavaScript SDKの `getAssetWithProof` ヘルパーはリーフセンチネルを `metadata.sellerFeeBasisPoints` に置きます。[継承ロイヤリティの読み取り](/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties)および[コレクションからロイヤリティを継承する](/ja/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)を参照してください。 + cNFTのメタデータは、図に示され以下に説明されているように複数回ハッシュ化されます： {% diagram %} @@ -282,6 +285,7 @@ impl LeafSchema { | Term | Definition | |------|------------| | **MetadataArgsV2** | The Rust struct containing cNFT metadata (name, symbol, URI, royalties, creators, collection) | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | MPL-Core コレクションからロイヤリティが継承される場合に `seller_fee_basis_points` に保存されるセンチネル `65535` | | **Data Hash** | keccak-256 hash of the metadata combined with seller_fee_basis_points | | **Creator Hash** | keccak-256 hash of the creator array (address, verified flag, share for each creator) | | **Collection Hash** | keccak-256 hash of the collection public key (new in V2) | diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/index.md b/src/pages/ja/smart-contracts/bubblegum-v2/index.md index e5dca7c4c..fcb07eebf 100644 --- a/src/pages/ja/smart-contracts/bubblegum-v2/index.md +++ b/src/pages/ja/smart-contracts/bubblegum-v2/index.md @@ -3,7 +3,7 @@ title: 概要 metaTitle: 概要 - Bubblegum V2 description: Bubblegum V2と圧縮NFTの概要を説明します。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - compressed NFT - cNFT @@ -86,6 +86,7 @@ Bubblegum V2は、オリジナルのBubblegumプログラムの基盤の上に - **凍結・解凍機能**: 2種類の凍結/解凍が利用可能：1) cNFT所有者は、アセットレベルの制御のためにフリーズ権限をリーフデリゲートに委任でき、特定のイベント中の転送を防ぐことや権利確定メカニズムの実装など、さまざまなユースケースに柔軟性を提供します。2) コレクション作成時に`PermanentFreezeDelegate`プラグインが有効になっている場合、プロジェクト作成者は永続フリーズデリゲートを通じてcNFTを凍結・解凍でき、コレクション全体の制御が可能です - **MPL-Coreコレクション統合**: Bubblegum V2 NFTは、トークンメタデータコレクションに限定されることなく、MPL-Coreコレクションに追加できるようになり、より大きなMetaplexエコシステムとの柔軟性と統合を可能にします。 - **ロイヤリティ強制**: Bubblegum V2は[MPL-Core](/ja/smart-contracts/core)コレクションを使用しているため、`ProgramDenyList`などを使用してcNFTにロイヤリティを強制することが可能です。 +- **継承ロイヤリティ**: MPL-CoreコレクションにミントされたcNFTは、リーフにセンチネルのセラーフィーベーシスポイント値（`65535`）を保存し、すべてのミントでベーシスポイントを複製する代わりにコレクションのRoyaltiesプラグイン設定を継承できます。 - **ソウルバウンドNFT**: cNFTをソウルバウンド（転送不可）にすることが可能になり、所有者のウォレットに永続的に紐づけられます。これは資格、出席証明、身元確認などに最適です。コレクション作成時に`PermanentFreezeDelegate`プラグインを有効にする必要があります。 - **永続転送の許可**: コレクションで`PermanentTransferDelegate`プラグインが有効になっている場合、永続転送デリゲートはリーフ所有者の相互作用なしにcNFTを新しい所有者に転送できます。 - **権限によるバーン**: コレクションに`PermanentBurnDelegate`プラグインが有効になっている場合、デリゲートはリーフ所有者の署名なしにNFTをバーンできます。 diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/mint-cnfts.md b/src/pages/ja/smart-contracts/bubblegum-v2/mint-cnfts.md index 3639ff5a4..eb041c11f 100644 --- a/src/pages/ja/smart-contracts/bubblegum-v2/mint-cnfts.md +++ b/src/pages/ja/smart-contracts/bubblegum-v2/mint-cnfts.md @@ -3,7 +3,7 @@ title: 圧縮NFTのミント metaTitle: 圧縮NFTのミント - Bubblegum V2 description: Bubblegum V2で圧縮NFTをミントする方法を学びます。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - mint compressed NFT - mint cNFT @@ -28,7 +28,9 @@ faqs: - q: 誰でも私のツリーからミントできますか？ a: ツリーがパブリックに設定されている場合のみです。プライベートツリーでは、ツリー作成者またはツリーデリゲートのみがミントできます。 - q: ミントに必要なメタデータフィールドは何ですか？ - a: MetadataArgsV2にはname、uri、sellerFeeBasisPoints、collection（またはnone）、そしてcreatorsの配列が必要です。 + a: MetadataArgsV2にはname、uri、sellerFeeBasisPoints、collection（またはnone）、creatorsの配列が必要です。 + - q: cNFTはMPL-Coreコレクションからロイヤリティを継承できますか？ + a: はい。Royaltiesプラグインを持つコレクションにミントする場合、sellerFeeBasisPointsを省略（またはSELLER_FEE_BASIS_POINTS_INHERITセンチネルを渡す）できます。リーフには65535（0xffff）が保存され、DASはroyalty.basis_pointsにコレクション料率を、royalty.basis_points_rawにセンチネルを置きます。 --- ## Summary @@ -39,6 +41,7 @@ faqs: - Mint directly into an MPL-Core collection with the BubblegumV2 plugin - Retrieve the asset ID and leaf schema from the mint transaction - Configure metadata including name, URI, creators, and royalties +- MPL-CoreコレクションのRoyaltiesプラグインからセラーフィーベーシスポイントを継承する [前のページ](/ja/smart-contracts/bubblegum-v2/create-trees)では、圧縮NFTをミントするためにBubblegumツリーが必要であることを確認し、その作成方法を見ました。今度は、与えられたBubblegumツリーから圧縮NFTをミントする方法を見てみましょう。 {% .lead %} @@ -146,6 +149,28 @@ await createCollection(umi, { {% /dialect %} {% /dialect-switcher %} +## コレクションからロイヤリティを継承する + +MPL-Coreコレクションにミントする場合、コレクションのロイヤリティ率をすべてのcNFTにコピーする代わりに、リーフに**センチネル**のセラーフィーベーシスポイント値（`65535`、`SELLER_FEE_BASIS_POINTS_INHERIT` / `0xffff` としてエクスポート）を保存できます。DASは表示用に `royalty.basis_points` / `creators` にコレクションから解決された料率を置き、`royalty.basis_points_raw` / `creators_raw` にリーフセンチネルを置き（`royalty.inherited: true`）、オンチェーンのリーフはハッシュ化のためにセンチネルを保持します。 + +DASレスポンスを**読む**クライアント（ウォレット、マーケットプレイス、インデクサー、アプリ）は[継承ロイヤリティの読み取り](/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties)に従ってください。 + +JavaScript SDKの `mintV2` ヘルパーは、`coreCollection` が指定され `metadata.sellerFeeBasisPoints` が省略された場合、この動作をデフォルトとします。 + +**要件:** + +- MPL-Coreコレクションには `BubblegumV2` と `Royalties` の両方のプラグインが必要です。 +- 継承されたセラーフィーを使用する場合、`metadata.creators` は**空の配列**である必要があります。クリエイター分配はリーフレベルのクリエイターではなく、コレクションのRoyaltiesプラグインから取得されます。 +- 継承されたセラーフィーはコレクション内のcNFTでのみ有効です。コレクションなしのミントでは `0` から `10000` の明示的な値を使用する必要があります。 + +{% code-tabs-imported from="bubblegum/mint-inherit-royalties" frameworks="umi" /%} + +単一のミントでコレクションのデフォルトを上書きするために、明示的な `sellerFeeBasisPoints` を渡すこともできます。 + +{% callout type="note" title="コレクションの削除" %} +継承されたセラーフィーを持つcNFTは、セラーフィーが明示的な値に更新されるまでコレクションから削除できません。[コレクションの管理](/ja/smart-contracts/bubblegum-v2/collections#inherited-royalties)および[圧縮NFTの更新](/ja/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)を参照してください。 +{% /callout %} + ### ミントトランザクションからアセットIDとリーフスキーマを取得する {% #get-leaf-schema-from-mint-transaction %} `parseLeafFromMintV2Transaction`ヘルパーを使用して、`mintV2`トランザクションからリーフを取得し、アセットIDを特定できます。この関数はトランザクションを解析するため、`parseLeafFromMintV2Transaction`を呼び出す前にトランザクションが完了していることを確認してください。 @@ -178,6 +203,7 @@ const assetId = leaf.id; - The Bubblegum Tree must be created before minting. See [Creating Trees](/ja/smart-contracts/bubblegum-v2/create-trees). - For collection mints, the MPL-Core collection must have the `BubblegumV2` plugin enabled. +- コレクションからロイヤリティを継承するには、コレクションに `Royalties` プラグインも必要で、リーフの `creators` 配列は空である必要があります。 - The collection authority must sign the transaction when minting to a collection, regardless of whether the tree is public or private. - Use `parseLeafFromMintV2Transaction` only after the transaction is **finalized**, not just confirmed. @@ -197,7 +223,11 @@ MPL-Coreコレクションアドレスに設定された`coreCollection`パラ ### ミントに必要なメタデータフィールドは何ですか？ -`MetadataArgsV2`には、name、uri、sellerFeeBasisPoints、collection（またはnone）、およびcreatorsの配列が必要です。 +`MetadataArgsV2` 構造体には以下が必要です：`name`（文字列）、`uri`（JSONメタデータを指す文字列）、`sellerFeeBasisPoints`（0-10000、またはコレクションにミントしてRoyaltiesプラグインから継承する場合は省略）、`collection`（公開鍵またはnone）、`creators`（クリエイターオブジェクトの配列。ロイヤリティを継承する場合は空である必要があります）。 + +### cNFTはMPL-Coreコレクションからロイヤリティを継承できますか？ + +はい。`coreCollection` でミントする場合、`metadata.sellerFeeBasisPoints` を省略し、`metadata.creators` を空にしてください。SDKはリーフに `SELLER_FEE_BASIS_POINTS_INHERIT`（`65535`）を保存します。コレクションには `Royalties` プラグインが必要です。[コレクションからロイヤリティを継承する](#inheriting-royalties-from-the-collection)を参照してください。 ## Glossary @@ -205,6 +235,7 @@ MPL-Coreコレクションアドレスに設定された`coreCollection`パラ |------|------------| | **mintV2** | The Bubblegum V2 instruction for minting compressed NFTs, replacing the V1 mint instructions | | **MetadataArgsV2** | The metadata structure passed to mintV2, containing name, URI, royalties, collection, and creators | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | Sentinel value `65535` (`0xffff`) stored on-chain to indicate royalties are inherited from the MPL-Core collection | | **Collection Authority** | The signer authorized to manage the MPL-Core collection — required when minting to a collection | | **BubblegumV2 Plugin** | An MPL-Core collection plugin that enables Bubblegum V2 features (freeze, soulbound, royalties) | | **Asset ID** | A PDA derived from the merkle tree address and leaf index, uniquely identifying a compressed NFT | diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties.md b/src/pages/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties.md new file mode 100644 index 000000000..a04715e15 --- /dev/null +++ b/src/pages/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties.md @@ -0,0 +1,164 @@ +--- +title: 継承ロイヤリティの読み取り +metaTitle: 継承ロイヤリティの読み取り - Bubblegum V2 - Metaplex +description: ウォレット、マーケットプレイス、インデクサー、その他のクライアントが、MPL-Coreコレクションから販売者手数料を継承するBubblegum V2 cNFTのDAS getAssetレスポンスをどのように読むべきかを説明します。 +created: '07-16-2026' +updated: '08-06-2026' +keywords: + - inherited royalties + - seller fee basis points + - DAS API + - getAsset + - basis_points_raw + - creators_raw + - inherited + - Bubblegum V2 +about: + - Compressed NFTs + - DAS API + - Royalties +proficiencyLevel: Intermediate +programmingLanguage: + - JavaScript + - TypeScript +faqs: + - q: royalty.basis_points_rawが65535と表示されるのはなぜですか？ + a: リーフハッシュに使われるオンチェーン継承センチネルです。royalty.basis_pointsにはすでに表示用のコレクション料率が入っています。 + - q: 継承されたcNFTでcreators_rawが空なのはなぜですか？ + a: SFBPが継承される場合、リーフのcreatorsは空でなければなりません。コレクションのロイヤリティ受取人にはcreatorsを使用してください。 + - q: 継承していないcNFTについて変更は必要ですか？ + a: いいえ。継承を使用しない場合、_rawフィールドとinheritedは省略され、主なroyaltyとcreatorsフィールドは従来どおり動作します。 +--- + +## 概要 + +Bubblegum V2は、リーフ上に販売者手数料を**継承センチネル**（`65535`）として保存し、MPL-CoreコレクションのRoyaltiesプラグインから実効料率を解決できます。DASは**コレクションから解決された値を主フィールドに置き**（表示用）、リーフ値は `_raw` フィールドに公開します（ハッシュ用）。 + +- **主フィールド**（`royalty.basis_points`、`creators`）はロイヤリティUIと支払い表示に使用 +- **`_raw` フィールド**（`royalty.basis_points_raw`、`creators_raw`）は証明、ハッシュ、書き込み命令に使用 +- 非継承アセットは変更なし — `_raw` / `inherited` は省略されます + +このページは、`getAsset` / DASレスポンスを**読む**すべてのクライアント（ウォレット、マーケットプレイス、インデクサー、分析、アプリ）向けです。継承ロイヤリティのcNFTのミントと更新については、[ミント](/ja/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)および[更新](/ja/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)を参照してください。 + +## 適用条件 + +次の条件を満たすとき、cNFTは継承ロイヤリティを使用しています。 + +- `Royalties` プラグインを持つMPL-Coreコレクション内のBubblegum V2アセットであり、かつ +- リーフの販売者手数料が継承センチネル `65535`（`0xffff`）である + +コレクションロイヤリティを主フィールドに解決できる場合、DASは `royalty.inherited: true` と `royalty.basis_points_raw: 65535` でこれを示します。 + +## フィールド対応表 + +| 用途 | フィールド | +|------|------------| +| 表示料率 / ロイヤリティUI | `royalty.basis_points`、`royalty.percent` | +| 受取人表示 / 支払い分割 | `creators` | +| ハッシュ、マークル証明、書き込み命令 | `royalty.basis_points_raw`、`creators_raw` | +| 継承モードの検出 | `royalty.inherited`（または `basis_points_raw === 65535`） | + +### 例: DASレスポンス（継承） + +```json +"royalty": { + "royalty_model": "creators", + "target": null, + "percent": 0.075, + "basis_points": 750, + "basis_points_raw": 65535, + "inherited": true, + "primary_sale_happened": false, + "locked": false +}, +"creators": [ + { + "address": "CJkzXwVwqiaSvMuRb3obrZHdrPFjCMBJBDrjspn72tDv", + "share": 100, + "verified": true + } +], +"creators_raw": [] +``` + +- `basis_points: 750` はユーザーに見せるコレクション料率（7.5%）です。 +- `basis_points_raw: 65535` はリーフデータハッシュに使われるオンチェーンセンチネルであり — **655.35%のロイヤリティではありません**。 +- `creators` はコレクション Royalties プラグインの受取人、`creators_raw: []` はハッシュ用のリーフ creators 配列です。 + +コレクションを解決できない場合、`basis_points` はフォールバックすることがあり、`basis_points_raw` は `65535` のままです。 + +## 検出と表示ヘルパー + +```ts +const INHERIT = 0xffff // 65535 + +function isInheritedRoyalty(royalty: { + basis_points: number + basis_points_raw?: number | null + inherited?: boolean | null +}): boolean { + return ( + royalty.inherited === true || + royalty.basis_points_raw === INHERIT + ) +} + +function leafBasisPoints(royalty: { + basis_points: number + basis_points_raw?: number | null + inherited?: boolean | null +}): number { + if (royalty.basis_points_raw != null) return royalty.basis_points_raw + if (royalty.inherited) return INHERIT + return royalty.basis_points +} + +function leafCreators(asset: { + creators: Array<{ address: string; share: number; verified: boolean }> + creators_raw?: Array<{ + address: string + share: number + verified: boolean + }> | null +}) { + return asset.creators_raw ?? asset.creators +} +``` + +`@metaplex-foundation/digital-asset-standard-api` を使う場合: + +```ts +import { + SELLER_FEE_BASIS_POINTS_INHERIT, + isInheritedSfbpRoyalty, + getRawSellerFeeBasisPoints, + getResolvedSellerFeeBasisPoints, +} from '@metaplex-foundation/digital-asset-standard-api' + +const royalty = asset.royalty +if (isInheritedSfbpRoyalty(royalty)) { + const rate = getResolvedSellerFeeBasisPoints(royalty) // e.g. 750 (display) + const leaf = getRawSellerFeeBasisPoints(royalty) // 65535 + const payees = asset.creators // collection payees + const leafCreators = asset.creators_raw ?? [] +} +``` + +## やってはいけないこと + +- `65535` や `6.5535%` をユーザー向けロイヤリティ料率として**表示しないでください** — その値は `basis_points_raw` にあります。 +- 空の `creators_raw` がロイヤリティ受取人がいないことを意味すると**仮定しないでください**；表示用の受取人は `creators` にあります。 +- リーフハッシュの再計算や Bubblegum 書き込み命令の構築時に、主フィールドの `basis_points` / `creators` を**使わないでください** — `basis_points_raw` と `creators_raw` を使ってください。 + +## Bubblegum SDK の注意 + +`getAssetWithProof` は書き込み命令が正しくハッシュされるよう、DASの**リーフ**フィールド（`basis_points_raw`、`creators_raw`）から `metadata` を構築します。`getAssetWithProof` 後にUI料率が必要な場合は、`rpcAsset.royalty.basis_points` と `rpcAsset.creators` を読んでください。[JavaScript SDK](/ja/smart-contracts/bubblegum-v2/sdk/javascript#getassetwithproof-and-inherited-royalties)を参照してください。 + +## 関連 + +- [圧縮NFTの取得](/ja/smart-contracts/bubblegum-v2/fetch-cnfts) +- [ミント — ロイヤリティの継承](/ja/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection) +- [cNFTの更新 — 継承ロイヤリティ](/ja/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties) +- [NFTデータのハッシュ](/ja/smart-contracts/bubblegum-v2/hashed-nft-data) +- [DAS getAsset](/ja/dev-tools/das-api/methods/get-asset) +- [FAQ — 継承ロイヤリティ](/ja/smart-contracts/bubblegum-v2/faq#inherited-royalties) diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/sdk/javascript.md b/src/pages/ja/smart-contracts/bubblegum-v2/sdk/javascript.md index 7935afe58..95f0ea940 100644 --- a/src/pages/ja/smart-contracts/bubblegum-v2/sdk/javascript.md +++ b/src/pages/ja/smart-contracts/bubblegum-v2/sdk/javascript.md @@ -3,7 +3,7 @@ title: JavaScript SDK metaTitle: JavaScript SDK - Bubblegum V2 - Metaplex description: Metaplex Bubblegum V2 JavaScript SDKの完全なリファレンス。Umiのセットアップ、ツリーの作成、ミント、転送、バーン、更新、委任、フリーズ、圧縮NFTのフェッチを網羅。 created: '01-15-2025' -updated: '02-25-2026' +updated: '06-19-2026' keywords: - mpl-bubblegum JavaScript - Bubblegum V2 TypeScript SDK @@ -39,7 +39,7 @@ faqs: - q: このSDKをBubblegum V1ツリーで使用できますか？ a: いいえ。このSDKはBubblegum V2を対象としておりLeafSchemaV2を使用します。V1ツリーにはレガシーBubblegum SDKを使用してください。 - q: getAssetWithProofとは何で、なぜ必要なのですか？ - a: getAssetWithProofは、DAS APIからリーフ変更命令に必要なすべてのパラメーター（プルーフ、ルート、リーフインデックス、ノンス、メタデータ）を1回の呼び出しで取得するヘルパーです。ほぼすべての書き込み命令にこれが必要です。 + a: getAssetWithProofは、DAS APIからリーフ変更命令に必要なすべてのパラメーター（プルーフ、ルート、リーフインデックス、ノンス、メタデータ）を1回の呼び出しで取得するヘルパーです。継承ロイヤリティの場合、metadata.sellerFeeBasisPointsはオンチェーンリーフセンチネル（65535）であり、解決済みのコレクション料率はrpcAsset.royalty.basis_pointsにあります。 --- **Bubblegum V2 JavaScript SDK**（`@metaplex-foundation/mpl-bubblegum`）は、Solanaで[圧縮NFT](/ja/smart-contracts/bubblegum-v2)を作成・管理するための推奨TypeScript/JavaScriptライブラリです。[Umiフレームワーク](/ja/dev-tools/umi)をベースに構築されており、すべてのBubblegum V2操作に対してタイプセーフな関数を提供し、[DAS API](/ja/smart-contracts/bubblegum-v2/fetch-cnfts)プラグインが自動的に含まれています。 {% .lead %} @@ -197,6 +197,14 @@ await mintV2(umi, { }).sendAndConfirm(umi) ``` +### コレクションからロイヤリティを継承する + +`coreCollection` が設定されている場合、SDKの `mintV2` ヘルパーは `metadata.sellerFeeBasisPoints` が省略されていれば継承ロイヤリティをデフォルトとします。リーフには `SELLER_FEE_BASIS_POINTS_INHERIT`（`65535`）が保存されます。コレクションには `Royalties` プラグインが必要で、`metadata.creators` は空である必要があります。 + +{% code-tabs-imported from="bubblegum/mint-inherit-royalties" frameworks="umi" /%} + +[圧縮NFTのミント — ロイヤリティの継承](/ja/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)でコレクション設定と制約を参照してください。 + ### ミント後のアセットIDの取得 ミントが確認された後、`parseLeafFromMintV2Transaction`を使用してリーフスキーマ（アセットIDを含む）を取得します。 @@ -276,13 +284,26 @@ const updateArgs: UpdateArgsArgs = { await updateMetadataV2(umi, { ...assetWithProof, leafOwner: assetWithProof.leafOwner, - currentMetadata: assetWithProof.metadata, + // 既存リーフメタデータの命令引数名（V2のcollectionは公開鍵）。 + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(publicKey('YourCollectionAddressHere')), + }, updateArgs, // If cNFT belongs to a collection, pass the collection address: coreCollection: publicKey('YourCollectionAddressHere'), }).sendAndConfirm(umi) ``` +`getAssetWithProof.metadata` は常にリーフを反映します（ロイヤリティ継承時は `65535` を含む）。表示には `rpcAsset.royalty.basis_points` と `rpcAsset.creators` を読んでください。 + ## 圧縮NFTの委任 [リーフデリゲート](/ja/smart-contracts/bubblegum-v2/delegate-cnfts)は、オーナーに代わってcNFTを転送、バーン、フリーズできます。デリゲートは転送後に新しいオーナーにリセットされます。 @@ -484,6 +505,21 @@ await unverifyCreatorV2(umi, { DAS APIプラグインは`mplBubblegum()`によって自動的に登録されます。利用可能なメソッドの詳細については[cNFTのフェッチ](/ja/smart-contracts/bubblegum-v2/fetch-cnfts)を参照してください。 +### getAssetWithProof and inherited royalties {% #getassetwithproof-and-inherited-royalties %} + +`getAssetWithProof` は `getAsset` と `getAssetProof` を書き込み命令が期待するパラメータ形状に結合します。 + +| Field | Purpose | +|-------|---------| +| `metadata` | ハッシュと書き込み命令用のリーフ正規メタデータ（`basis_points_raw` / `creators_raw` から構成）。ロイヤリティが継承されている場合、`sellerFeeBasisPoints` は `65535`、`creators` はリーフのクリエイターリスト（通常は空）です。 | +| `rpcAsset` | 完全なDASレスポンス。コレクションから解決された表示値は `royalty.basis_points`、`royalty.percent`、`creators` にあり、リーフ値は `royalty.basis_points_raw` と `creators_raw` にあります。 | + +`updateMetadataV2` は既存リーフ引数名を引き続き `currentMetadata`（IDL）とします。V2 の `collection` を公開鍵にして、`assetWithProof.metadata` のリーフフィールドからその `MetadataArgsV2` を構築してください。 + +DASを直接読むクライアントは[継承ロイヤリティの読み取り](/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties)に従ってください。 + +{% code-tabs-imported from="bubblegum/get-asset-with-proof-inherited" frameworks="umi" /%} + ### 単一cNFTのフェッチ ```ts {% title="fetch-asset.ts" %} @@ -606,7 +642,8 @@ RPCプロバイダーがMetaplex DAS APIをサポートしていない可能性 | `setNonTransferableV2` | cNFTを永続的にソウルバウンドにする（不可逆） | | `verifyCreatorV2` | クリエイターエントリにverifiedフラグを設定する | | `unverifyCreatorV2` | クリエイターエントリからverifiedフラグを削除する | -| `getAssetWithProof` | 書き込み命令に必要なすべてのプルーフパラメーターをフェッチする | +| `getAssetWithProof` | プルーフパラメーターを取得；`metadata` はリーフ正規値、表示用の継承値は `rpcAsset` 上 | +| `SELLER_FEE_BASIS_POINTS_INHERIT` | MPL-Coreコレクションから継承されたロイヤリティのセンチネル定数（`65535`） | | `findLeafAssetIdPda` | ツリーアドレスとリーフインデックスからcNFTアセットIDを導出する | | `parseLeafFromMintV2Transaction` | ミントトランザクションからリーフスキーマ（アセットIDを含む）を抽出する | diff --git a/src/pages/ja/smart-contracts/bubblegum-v2/update-cnfts.md b/src/pages/ja/smart-contracts/bubblegum-v2/update-cnfts.md index 6193bd977..5f9659318 100644 --- a/src/pages/ja/smart-contracts/bubblegum-v2/update-cnfts.md +++ b/src/pages/ja/smart-contracts/bubblegum-v2/update-cnfts.md @@ -3,7 +3,7 @@ title: 圧縮NFTの更新 metaTitle: 圧縮NFTの更新 - Bubblegum V2 description: Bubblegum V2で圧縮NFTを更新する方法を学びます。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - update compressed NFT - update cNFT @@ -24,6 +24,8 @@ faqs: a: UpdateArgsArgsで定義された名前、URI、セラーフィーベーシスポイント、その他のメタデータフィールドを更新できます。変更したいフィールドにはsome('newValue')を使用します。 - q: 更新時にコレクションを渡す必要がありますか？ a: はい、cNFTがコレクションに属している場合。コレクションの公開鍵とともにcoreCollectionパラメータを渡します。コレクション権限がトランザクションに署名する必要があります。 + - q: コレクションからロイヤリティを継承しているcNFTを更新するにはどうすればよいですか？ + a: getAssetWithProofのリーフメタデータをupdateMetadataV2のcurrentMetadata引数（既存リーフ状態のIDL名）として渡します。ロイヤリティが継承されている場合、sellerFeeBasisPointsはオンチェーンセンチネルです。 --- ## Summary @@ -34,6 +36,7 @@ faqs: - コレクション権限はコレクションに属するcNFTを更新する - ツリー権限はコレクションに属さないcNFTを更新する - 変更はマークルツリーに反映され、DAS APIプロバイダーによってインデックス化されます +- `getAssetWithProof` のリーフメタデータを `updateMetadataV2` の `currentMetadata` 引数（既存リーフ状態のIDL名）として使用する **updateMetadataV2**命令は、圧縮NFTのメタデータを変更するために使用できます。マークルルートは、データの伝播されたハッシュを反映するように更新され、[Metaplex DAS API](https://github.com/metaplex-foundation/digital-asset-standard-api)に準拠するRPCプロバイダーは、cNFTのインデックスを更新します。 @@ -90,7 +93,17 @@ const updateArgs: UpdateArgsArgs = { await updateMetadataV2(umi, { ...assetWithProof, leafOwner, - currentMetadata: assetWithProof.metadata, + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(publicKey('22222222222222222222222222222222')), + }, updateArgs, // オプションパラメータ。権限が現在のumiアイデンティティと // 異なる署名者型の場合、ここでその署名者を割り当てます。 @@ -100,6 +113,22 @@ await updateMetadataV2(umi, { }).sendAndConfirm(umi) ``` +{% callout type="note" title="書き込み命令用のリーフメタデータ" %} +`getAssetWithProof.metadata` は常にリーフ正規値です — ロイヤリティが継承されている場合は `sellerFeeBasisPoints: 65535` を含みます。コレクションから解決された表示値は `rpcAsset.royalty.basis_points` と `rpcAsset.creators` にあります。 + +`updateMetadataV2` の `currentMetadata` 引数は既存リーフメタデータのIDL名です（V2形状: `collection` は公開鍵）。`assetWithProof.metadata` から構築してください。 + +アセット読み取り時のDASレスポンスフィールドについては、[継承ロイヤリティの読み取り](/ja/smart-contracts/bubblegum-v2/reading-inherited-royalties)を参照してください。 +{% /callout %} + +## 継承されたロイヤリティ {% #inherited-royalties %} + +`updateArgs.sellerFeeBasisPoints` を `some(SELLER_FEE_BASIS_POINTS_INHERIT)` に設定することで、cNFTを継承ロイヤリティ**へ**切り替えられます。コレクションには `Royalties` プラグインが必要で、更新後のメタデータの `creators` 配列は空である必要があります。 + +継承ロイヤリティ**から**明示的なパーセンテージに戻すには — 例えば[cNFTをコレクションから削除する](/ja/smart-contracts/bubblegum-v2/collections#inherited-royalties)前に — 希望するベーシスポイントを渡します： + +{% code-tabs-imported from="bubblegum/update-inherit-royalties" frameworks="umi" /%} + {% /totem %} {% /dialect %} {% /dialect-switcher %} @@ -107,8 +136,27 @@ await updateMetadataV2(umi, { ## Notes - 更新権限は、cNFTがコレクションに属しているかどうかによって異なります。コレクションcNFTはコレクション権限を使用し、スタンドアロンcNFTはツリー権限を使用します。 -- 更新を適用する前にプログラムが現在のリーフを検証できるよう、`getAssetWithProof`からの`currentMetadata`を渡す必要があります。 +- プログラムが更新を適用する前に現在のリーフを検証できるよう、`getAssetWithProof` のリーフメタデータを `updateMetadataV2` の `currentMetadata` 引数として渡してください。 - 更新したいフィールドには`some()`を使用し、変更しないフィールドは省略します。 +- 継承されたセラーフィーには、リーフレベルの空の`creators`配列と`Royalties`プラグインを持つコレクションが必要です。 + +## FAQ + +### 圧縮NFTのメタデータを更新できるのは誰ですか？ + +cNFTがコレクションに属している場合、更新できるのはコレクション権限のみです。コレクションに属していない場合、ツリー権限（ツリー作成者またはデリゲート）が更新できます。 + +### cNFTで更新できるフィールドは何ですか？ + +`UpdateArgsArgs`で定義された名前、URI、セラーフィーベーシスポイント、その他のメタデータフィールドを更新できます。変更したいフィールドには`some('newValue')`を使用します。 + +### 更新時にコレクションを渡す必要がありますか？ + +はい、cNFTがコレクションに属している場合。コレクションの公開鍵とともに`coreCollection`パラメータを渡します。コレクション権限がトランザクションに署名する必要があります。 + +### コレクションからロイヤリティを継承しているcNFTを更新するにはどうすればよいですか？ + +検証にオンチェーンセンチネルが使われるよう、`getAssetWithProof` のリーフメタデータを `updateMetadataV2` の `currentMetadata` 引数として渡します。継承ロイヤリティに切り替えるには`updateArgs.sellerFeeBasisPoints`に`some(SELLER_FEE_BASIS_POINTS_INHERIT)`を、切り替えるには明示的な数値を使用します。 ## Glossary @@ -118,4 +166,5 @@ await updateMetadataV2(umi, { | **コレクション権限** | MPL-Coreコレクションの更新権限。そのコレクション内のcNFTを更新する権限がある | | **ツリー権限** | コレクションに属さないcNFTを更新する権限を持つツリー作成者またはデリゲート | | **UpdateArgsArgs** | どのメタデータフィールドをOptionラッパーを使用して更新するかを定義するTypeScript型 | -| **currentMetadata** | getAssetWithProofで取得したcNFTの既存メタデータ。検証に必要 | +| **currentMetadata** | 既存リーフメタデータに対する `updateMetadataV2` のIDL引数；`getAssetWithProof.metadata` から構築する | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | MPL-Coreコレクションからロイヤリティが継承されることを示すセンチネル値 `65535` | diff --git a/src/pages/ko/dev-tools/das-api/methods/get-asset.md b/src/pages/ko/dev-tools/das-api/methods/get-asset.md index 39548e384..bb34c3337 100644 --- a/src/pages/ko/dev-tools/das-api/methods/get-asset.md +++ b/src/pages/ko/dev-tools/das-api/methods/get-asset.md @@ -7,6 +7,8 @@ tableOfContents: false 메타데이터 및 소유자를 포함한 압축된/표준 자산의 정보를 반환합니다. +MPL-Core 컬렉션에서 판매자 수수료를 상속하는 Bubblegum V2 cNFT의 경우, 컬렉션에서 해석된 표시 값은 `royalty.basis_points` / `creators`에 있고, 리프 값은 `royalty.basis_points_raw` / `creators_raw`에 있습니다(`royalty.inherited: true`). [상속 로열티 읽기](/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties)를 참조하세요. + ## 매개변수 | 이름 | 필수 | 설명 | diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/collections.md b/src/pages/ko/smart-contracts/bubblegum-v2/collections.md index bd69559b2..cdd9a377f 100644 --- a/src/pages/ko/smart-contracts/bubblegum-v2/collections.md +++ b/src/pages/ko/smart-contracts/bubblegum-v2/collections.md @@ -3,7 +3,7 @@ title: 컬렉션 관리 metaTitle: 컬렉션 관리 - Bubblegum V2 description: Bubblegum에서 컬렉션을 설정, 확인 및 확인 해제하는 방법을 알아보세요. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - NFT collection - verify collection @@ -26,6 +26,8 @@ faqs: a: 예. coreCollection(현재)과 newCoreCollection(새로운) 매개변수 모두와 함께 setCollectionV2를 사용하세요. 두 컬렉션 권한이 모두 서명해야 합니다. - q: BubblegumV2 플러그인이란 무엇인가요? a: 컬렉션에서 동결/해동, 소울바운드 cNFT, 로열티 강제와 같은 Bubblegum V2 기능을 활성화하는 MPL-Core 컬렉션 플러그인입니다. + - q: 로열티를 상속하는 cNFT를 컬렉션에서 제거할 수 있나요? + a: 아니요. 먼저 sellerFeeBasisPoints를 명시적인 값으로 업데이트한 다음 setCollectionV2로 컬렉션을 제거하세요. --- ## Summary @@ -119,15 +121,38 @@ const signature = await setCollectionV2(umi, { {% /dialect %} {% /dialect-switcher %} +## 상속된 로열티 {% #inherited-royalties %} + +[컬렉션에서 seller fee basis points를 상속](/ko/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)하여 민팅된 cNFT는 리프에 센티널 값 `65535`를 저장합니다. 이는 컬렉션 관리에 영향을 줍니다: + +- **컬렉션 제거** — 리프가 여전히 상속 센티널을 사용하는 동안 `setCollectionV2`는 작업을 거부합니다. 먼저 [`updateMetadataV2`](/ko/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)를 통해 cNFT의 `sellerFeeBasisPoints`를 명시적인 값으로 업데이트하세요. +- **다른 컬렉션으로 이동** — 대상 컬렉션에 `Royalties` 플러그인이 있으면 허용됩니다. cNFT는 상속 센티널을 유지하고 새 컬렉션에서 로열티를 해석합니다. +- **로열티가 없는 컬렉션으로 이동** — `CollectionMustHaveRoyaltiesPlugin`으로 거부됩니다. + ## Notes - The MPL-Core collection must have the `BubblegumV2` plugin enabled before cNFTs can be added to it. - Unlike Bubblegum V1 (which uses Token Metadata collections with a "verified" boolean), V2 uses MPL-Core collections without verification flags. - When changing between collections, both the old and new collection authorities must sign the transaction. +- 상속된 seller fee를 사용하는 cNFT는 리프에서 로열티가 명시적인 값으로 설정될 때까지 컬렉션에서 제거할 수 없습니다. ## FAQ -# +### 민팅 후 cNFT를 컬렉션에 추가하려면 어떻게 해야 하나요? + +컬렉션의 공개 키로 `newCoreCollection` 매개변수를 설정하여 `setCollectionV2` 명령을 사용하세요. 컬렉션 권한이 서명해야 합니다. + +### cNFT의 컬렉션을 변경할 수 있나요? + +예. `coreCollection`(현재)과 `newCoreCollection`(새로운) 모두와 함께 `setCollectionV2`를 사용하세요. 권한이 다른 계정인 경우 두 컬렉션 권한이 모두 서명해야 합니다. + +### BubblegumV2 플러그인이란 무엇인가요? + +동결/해동, 소울바운드 cNFT, 로열티 강제, 컬렉션 수준의 영구 위임자 등 Bubblegum V2 기능을 활성화하는 MPL-Core 컬렉션 플러그인입니다. + +### 로열티를 상속하는 cNFT를 컬렉션에서 제거할 수 있나요? + +아니요. 프로그램은 `CannotRemoveFromCollectionWithInheritedSellerFee`를 반환합니다. 먼저 `updateMetadataV2`로 `sellerFeeBasisPoints`를 명시적인 값으로 설정한 다음 `setCollectionV2`를 호출하여 컬렉션을 제거하세요. ## Glossary diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/faq.md b/src/pages/ko/smart-contracts/bubblegum-v2/faq.md index 3598d4255..650bdeada 100644 --- a/src/pages/ko/smart-contracts/bubblegum-v2/faq.md +++ b/src/pages/ko/smart-contracts/bubblegum-v2/faq.md @@ -3,7 +3,7 @@ title: FAQ metaTitle: FAQ - Bubblegum V2 description: Bubblegum에 대한 자주 묻는 질문. created: '2025-01-15' -updated: '2026-02-24' +updated: '06-19-2026' keywords: - Bubblegum FAQ - compressed NFT questions @@ -35,6 +35,8 @@ faqs: a: 압축 해제는 Bubblegum V1 자산에서만 사용할 수 있습니다. V2는 압축 해제를 지원하지 않습니다. - q: 하나의 트리에 cNFT를 몇 개나 저장할 수 있나요? a: 최대값은 2^maxDepth입니다. 깊이 30의 트리는 10억 개 이상의 cNFT를 보유할 수 있지만, 트리가 클수록 렌트 비용이 더 많이 듭니다. + - q: cNFT가 MPL-Core 컬렉션에서 로열티를 상속할 수 있나요? + a: 예. Royalties 플러그인이 있는 컬렉션에 민팅할 때 sellerFeeBasisPoints를 생략하세요. 리프에는 상속 센티널(65535)이 저장되고 DAS는 royalty.basis_points에 컬렉션 비율을, royalty.basis_points_raw에 센티널을 둡니다. 쓰기 명령에는 getAssetWithProof.metadata(리프 값)를 사용하세요. --- ## Summary @@ -45,6 +47,7 @@ faqs: - `truncateCanopy` 또는 주소 조회 테이블로 "트랜잭션이 너무 큽니다" 오류 해결하기 - 트리를 생성하기 전에 트리 비용과 용량 이해하기 - Bubblegum V2는 V1 트리 또는 압축 해제와 하위 호환되지 않음 +- cNFT는 MPL-Core 컬렉션의 Royalties 플러그인에서 seller fee basis points를 상속할 수 있음 ## Bubblegum V2란 무엇인가요? @@ -148,3 +151,30 @@ await transferV2(umi, { 다른 접근 방식은 [버전화된 트랜잭션과 주소 조회 테이블](/ko/dev-tools/umi/toolbox/address-lookup-table)을 구현하는 것입니다. 이 방법은 트랜잭션 크기를 더 효과적으로 관리하는 데 도움이 될 수 있습니다. 이러한 기술을 적용하면 트랜잭션 크기 제한을 극복하고 작업을 성공적으로 실행할 수 있습니다. + +## 하나의 트리에 cNFT를 몇 개나 저장할 수 있나요? {% #tree-capacity %} + +cNFT의 최대 수는 `2^maxDepth`입니다. 깊이 14 트리는 16,384개, 깊이 20은 약 100만 개, 깊이 24는 약 1,600만 개, 깊이 30은 10억 개 이상의 cNFT를 보유할 수 있습니다. 모든 옵션은 [트리 용량 표](/ko/smart-contracts/bubblegum-v2/create-trees)를 참조하세요. + +## cNFT가 MPL-Core 컬렉션에서 로열티를 상속할 수 있나요? {% #inherited-royalties %} + +예. `Royalties` 플러그인이 있는 MPL-Core 컬렉션에 민팅할 때 `metadata.sellerFeeBasisPoints`를 생략하거나 `SELLER_FEE_BASIS_POINTS_INHERIT`(`65535`)를 전달할 수 있습니다. 리프에는 해당 센티널이 온체인에 저장됩니다. DAS는 표시용으로 `royalty.basis_points` / `creators`에 컬렉션에서 해석된 비율을 두고, `royalty.basis_points_raw` / `creators_raw`에 리프 센티널을 둡니다(`royalty.inherited: true`). + +**요구 사항:** + +- 컬렉션에 `BubblegumV2`와 `Royalties` 플러그인이 모두 있어야 합니다. +- 상속 seller fee를 사용할 때 `metadata.creators`는 빈 배열이어야 합니다. + +**`getAssetWithProof` 사용:** + +- **`metadata`** — 해싱 및 쓰기 명령을 위한 리프 정규 값(상속 시 `sellerFeeBasisPoints`는 `65535`). +- **`rpcAsset`** — 표시 / 지급 UI에는 `royalty.basis_points`와 `creators`를 사용하세요. + +`updateMetadataV2`를 호출할 때는 리프 메타데이터를 명령의 `currentMetadata` 인자(기존 리프 상태에 대한 IDL 이름)로 전달하세요. + +**컬렉션 관리:** + +- 상속된 seller fee를 사용하는 cNFT는 명시적인 `sellerFeeBasisPoints`로 업데이트할 때까지 컬렉션에서 **제거할 수 없습니다**. +- 대상에 `Royalties` 플러그인이 있으면 다른 컬렉션으로 이동할 수 있습니다. + +DAS를 읽는 클라이언트는 [상속 로열티 읽기](/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties)를 참조하고, 전체 예제는 [민팅 — 로열티 상속](/ko/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection), [cNFT 업데이트](/ko/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties), [컬렉션 관리](/ko/smart-contracts/bubblegum-v2/collections#inherited-royalties)를 참조하세요. diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/fetch-cnfts.md b/src/pages/ko/smart-contracts/bubblegum-v2/fetch-cnfts.md index f8f64e7c4..a173300c8 100644 --- a/src/pages/ko/smart-contracts/bubblegum-v2/fetch-cnfts.md +++ b/src/pages/ko/smart-contracts/bubblegum-v2/fetch-cnfts.md @@ -208,6 +208,7 @@ const rpcAssetList = await umi.rpc.getAssetsByGroup({ - Not all RPC providers support the DAS API. Check the [RPC Providers](/ko/rpc-providers) page for compatible options. - The DAS API plugin is automatically included when you install `mplBubblegum` — no separate installation needed. - Proofs fetched via `getAssetProof` may become stale if the tree is modified. Always fetch fresh proofs before performing write operations. +- 컬렉션에서 판매자 수수료를 상속하는 Bubblegum V2 cNFT의 경우, DAS는 `royalty.basis_points` / `creators`에 컬렉션 비율을, `royalty.basis_points_raw` / `creators_raw`에 리프 센티널을 둡니다. [상속 로열티 읽기](/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties)를 참조하세요. ## FAQ diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/hashed-nft-data.md b/src/pages/ko/smart-contracts/bubblegum-v2/hashed-nft-data.md index c02590fb2..caa5f334f 100644 --- a/src/pages/ko/smart-contracts/bubblegum-v2/hashed-nft-data.md +++ b/src/pages/ko/smart-contracts/bubblegum-v2/hashed-nft-data.md @@ -3,7 +3,7 @@ title: NFT 데이터 해싱 metaTitle: NFT 데이터 해싱 - Bubblegum V2 description: Bubblegum에서 NFT 데이터가 해싱되는 방식에 대해 자세히 알아보세요. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - hashed NFT data - merkle leaf @@ -281,7 +281,8 @@ pub struct MetadataArgsV2 { pub symbol: String, /// 자산을 나타내는 JSON을 가리키는 URI pub uri: String, - /// 2차 판매에서 창작자에게 지불되는 로열티 베이시스 포인트 (0-10000) + /// 2차 판매에서 창작자에게 지불되는 로열티 베이시스 포인트 (0-10000), + /// 또는 MPL-Core 컬렉션의 Royalties 플러그인에서 상속하려면 u16::MAX(65535). pub seller_fee_basis_points: u16, /// 불변, 한 번 뒤집히면 이 메타데이터의 모든 판매가 2차 판매로 간주됩니다. pub primary_sale_happened: bool, @@ -296,6 +297,8 @@ pub struct MetadataArgsV2 { } ``` +`seller_fee_basis_points`가 `65535`(`0xffff`, `SELLER_FEE_BASIS_POINTS_INHERIT`)이면 리프에는 리터럴 로열티 비율 대신 센티널이 저장됩니다. 데이터 해시는 컬렉션의 해석된 basis points가 아니라 이 센티널 값에서 계산됩니다. DAS는 `royalty.basis_points`에 컬렉션 비율을, `royalty.basis_points_raw`에 리프 센티널을 둡니다. JavaScript SDK의 `getAssetWithProof` 헬퍼는 리프 센티널을 `metadata.sellerFeeBasisPoints`에 둡니다. [상속 로열티 읽기](/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties) 및 [컬렉션에서 로열티 상속](/ko/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)을 참조하세요. + cNFT의 메타데이터는 아래 다이어그램에 표시되고 설명된 대로 여러 번 해싱됩니다: {% diagram %} @@ -523,6 +526,7 @@ impl LeafSchema { | Term | Definition | |------|------------| | **MetadataArgsV2** | The Rust struct containing cNFT metadata (name, symbol, URI, royalties, creators, collection) | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | MPL-Core 컬렉션에서 로열티가 상속될 때 `seller_fee_basis_points`에 저장되는 센티널 `65535` | | **Data Hash** | keccak-256 hash of the metadata combined with seller_fee_basis_points | | **Creator Hash** | keccak-256 hash of the creator array (address, verified flag, share for each creator) | | **Collection Hash** | keccak-256 hash of the collection public key (new in V2) | diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/index.md b/src/pages/ko/smart-contracts/bubblegum-v2/index.md index e7875eb57..d28234f5a 100644 --- a/src/pages/ko/smart-contracts/bubblegum-v2/index.md +++ b/src/pages/ko/smart-contracts/bubblegum-v2/index.md @@ -3,7 +3,7 @@ title: 개요 metaTitle: 개요 - Bubblegum V2 description: Bubblegum V2와 압축된 NFT에 대한 고수준 개요를 제공합니다. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - compressed NFT - cNFT @@ -85,7 +85,8 @@ Bubblegum V2는 원본 Bubblegum 프로그램의 기반 위에 구축되면서 - **동결 및 해동 기능**: 두 가지 유형의 동결/해동이 가능합니다: 1) cNFT 소유자는 자산 수준 제어를 위해 리프 위임자에게 동결 권한을 위임할 수 있어 특정 이벤트 중 전송을 방지하거나 베스팅 메커니즘을 구현하는 등 다양한 사용 사례에 유연성을 제공합니다. 2) 컬렉션 생성 시 `PermanentFreezeDelegate` 플러그인이 활성화된 경우, 프로젝트 제작자는 컬렉션 전체 제어를 위해 영구 동결 위임자를 통해 cNFT를 동결하고 해동할 수 있습니다 - **MPL-Core 컬렉션 통합**: Bubblegum V2 NFT는 이제 토큰 메타데이터 컬렉션에 제한되지 않고 MPL-Core 컬렉션에 추가될 수 있어 더 넓은 Metaplex 생태계와의 유연성과 통합을 제공합니다. -- **로열티 강제**: Bubblegum V2는 [MPL-Core](/smart-contracts/core) 컬렉션을 사용하므로 `ProgramDenyList`를 사용하여 cNFT에 로열티를 강제할 수 있습니다. +- **로열티 강제**: Bubblegum V2는 [MPL-Core](/ko/smart-contracts/core) 컬렉션을 사용하므로 `ProgramDenyList`를 사용하여 cNFT에 로열티를 강제할 수 있습니다. +- **상속 로열티**: MPL-Core 컬렉션에 민팅된 cNFT는 리프에 센티널 seller fee basis points 값(`65535`)을 저장하고, 모든 민트마다 basis points를 복제하는 대신 컬렉션의 Royalties 플러그인 설정을 상속할 수 있습니다. - **소울바운드 NFT**: cNFT는 이제 소울바운드(양도 불가능)로 만들 수 있어 소유자의 지갑에 영구적으로 바인딩됩니다. 이는 자격증명, 참석 증명, 신원 확인 등에 완벽합니다. 컬렉션 생성 시 `PermanentFreezeDelegate` 플러그인이 활성화되어야 합니다. - **영구 전송 허용**: 컬렉션에서 `PermanentTransferDelegate` 플러그인이 활성화된 경우 영구 전송 위임자는 리프 소유자의 상호 작용 없이 cNFT를 새 소유자에게 전송할 수 있습니다. - **권한에 의한 소각**: 컬렉션에 `PermanentBurnDelegate` 플러그인이 활성화된 경우, 위임자는 리프 소유자의 서명 없이 NFT를 소각할 수 있습니다. diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/mint-cnfts.md b/src/pages/ko/smart-contracts/bubblegum-v2/mint-cnfts.md index 0992141a8..a807fc4a7 100644 --- a/src/pages/ko/smart-contracts/bubblegum-v2/mint-cnfts.md +++ b/src/pages/ko/smart-contracts/bubblegum-v2/mint-cnfts.md @@ -3,7 +3,7 @@ title: 압축된 NFT 민팅 metaTitle: 압축된 NFT 민팅 - Bubblegum V2 description: Bubblegum V2에서 압축된 NFT를 민팅하는 방법을 알아보세요. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - mint compressed NFT - mint cNFT @@ -29,6 +29,8 @@ faqs: a: 트리가 공개로 설정된 경우에만 가능합니다. 비공개 트리의 경우 트리 생성자 또는 트리 위임자만 민팅할 수 있습니다. - q: 민팅에 필요한 메타데이터 필드는 무엇인가요? a: MetadataArgsV2에는 name, uri, sellerFeeBasisPoints, collection(또는 none), 그리고 creators 배열이 필요합니다. + - q: cNFT가 MPL-Core 컬렉션에서 로열티를 상속할 수 있나요? + a: 예. Royalties 플러그인이 있는 컬렉션에 민팅할 때 sellerFeeBasisPoints를 생략하거나(또는 SELLER_FEE_BASIS_POINTS_INHERIT 센티널을 전달) 할 수 있습니다. 리프에는 65535(0xffff)가 저장되며 DAS는 royalty.basis_points에 컬렉션 비율을, royalty.basis_points_raw에 센티널을 둡니다. --- ## Summary @@ -39,6 +41,7 @@ faqs: - Mint directly into an MPL-Core collection with the BubblegumV2 plugin - Retrieve the asset ID and leaf schema from the mint transaction - Configure metadata including name, URI, creators, and royalties +- MPL-Core 컬렉션의 Royalties 플러그인에서 seller fee basis points 상속 [이전 페이지](/ko/smart-contracts/bubblegum-v2/create-trees)에서 압축된 NFT를 민팅하려면 Bubblegum 트리가 필요하다는 것을 보았고, 하나를 만드는 방법을 보았습니다. 이제 주어진 Bubblegum 트리에서 압축된 NFT를 민팅하는 방법을 살펴보겠습니다. {% .lead %} @@ -142,6 +145,28 @@ await createCollection(umi, { {% /dialect %} {% /dialect-switcher %} +## 컬렉션에서 로열티 상속 + +MPL-Core 컬렉션에 민팅할 때 컬렉션의 로열티 비율을 모든 cNFT에 복사하는 대신 리프에 **센티널** seller fee basis points 값(`65535`, `SELLER_FEE_BASIS_POINTS_INHERIT` / `0xffff`로 내보냄)을 저장할 수 있습니다. DAS는 표시용으로 `royalty.basis_points` / `creators`에 컬렉션에서 해석된 비율을 두고, `royalty.basis_points_raw` / `creators_raw`에 리프 센티널을 두며(`royalty.inherited: true`), 온체인 리프는 해싱을 위해 센티널을 유지합니다. + +DAS 응답을 **읽는** 클라이언트(지갑, 마켓플레이스, 인덱서, 앱)는 [상속 로열티 읽기](/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties)를 따르세요. + +JavaScript SDK의 `mintV2` 헬퍼는 `coreCollection`이 제공되고 `metadata.sellerFeeBasisPoints`가 생략되면 이 동작을 기본값으로 사용합니다. + +**요구 사항:** + +- MPL-Core 컬렉션에는 `BubblegumV2`와 `Royalties` 플러그인이 모두 있어야 합니다. +- 상속된 seller fee를 사용할 때 `metadata.creators`는 **빈 배열**이어야 합니다. 크리에이터 분배는 리프 수준 크리에이터가 아니라 컬렉션의 Royalties 플러그인에서 가져옵니다. +- 상속된 seller fee는 컬렉션 내 cNFT에만 유효합니다. 컬렉션 없는 민팅은 `0`에서 `10000` 사이의 명시적인 값을 사용해야 합니다. + +{% code-tabs-imported from="bubblegum/mint-inherit-royalties" frameworks="umi" /%} + +단일 민트에 대해 컬렉션 기본값을 재정의하려면 명시적인 `sellerFeeBasisPoints`를 전달할 수 있습니다. + +{% callout type="note" title="컬렉션 제거" %} +상속된 seller fee를 사용하는 cNFT는 seller fee가 명시적인 값으로 업데이트될 때까지 컬렉션에서 제거할 수 없습니다. [컬렉션 관리](/ko/smart-contracts/bubblegum-v2/collections#inherited-royalties) 및 [압축 NFT 업데이트](/ko/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)를 참조하세요. +{% /callout %} + ### 민트 트랜잭션에서 자산 ID와 리프 스키마 가져오기 {% #get-leaf-schema-from-mint-transaction %} `parseLeafFromMintV2Transaction` 도우미를 사용하여 `mintV2` 트랜잭션에서 리프를 검색하고 자산 ID를 결정할 수 있습니다. 이 함수는 트랜잭션을 파싱하므로 `parseLeafFromMintV2Transaction`을 호출하기 전에 트랜잭션이 완료되었는지 확인해야 합니다. @@ -174,12 +199,31 @@ const assetId = leaf.id; - The Bubblegum Tree must be created before minting. See [Creating Trees](/smart-contracts/bubblegum-v2/create-trees). - For collection mints, the MPL-Core collection must have the `BubblegumV2` plugin enabled. +- 컬렉션에서 로열티를 상속하려면 컬렉션에 `Royalties` 플러그인도 있어야 하며 리프의 `creators` 배열은 비어 있어야 합니다. - The collection authority must sign the transaction when minting to a collection, regardless of whether the tree is public or private. - Use `parseLeafFromMintV2Transaction` only after the transaction is **finalized**, not just confirmed. ## FAQ -# +### 컬렉션에 압축 NFT를 민팅하려면 어떻게 해야 하나요? + +MPL-Core 컬렉션 주소로 `coreCollection` 매개변수를 설정하고 `collectionAuthority` 서명자를 제공하여 `mintV2` 명령을 사용하세요. 컬렉션에는 `BubblegumV2` 플러그인이 활성화되어 있어야 합니다. + +### 민팅 후 자산 ID를 가져오려면 어떻게 해야 하나요? + +트랜잭션이 완료된 후 `parseLeafFromMintV2Transaction` 헬퍼를 사용하세요. 트랜잭션을 파싱하고 `leaf.id`를 통해 자산 ID를 포함한 리프 스키마를 반환합니다. + +### 누구나 내 트리에서 민팅할 수 있나요? + +트리가 `public: true`로 생성된 경우에만 가능합니다. 비공개 트리의 경우 트리 생성자 또는 트리 위임자만 cNFT를 민팅할 수 있습니다. + +### 민팅에 필요한 메타데이터 필드는 무엇인가요? + +`MetadataArgsV2` 구조체에는 다음이 필요합니다: `name`(문자열), `uri`(JSON 메타데이터를 가리키는 문자열), `sellerFeeBasisPoints`(0-10000, 또는 컬렉션에 민팅하여 Royalties 플러그인에서 상속할 경우 생략), `collection`(공개 키 또는 none), `creators`(크리에이터 객체 배열. 로열티를 상속할 때는 비어 있어야 함). + +### cNFT가 MPL-Core 컬렉션에서 로열티를 상속할 수 있나요? + +예. `coreCollection`으로 민팅할 때 `metadata.sellerFeeBasisPoints`를 생략하고 `metadata.creators`를 비워 두세요. SDK는 리프에 `SELLER_FEE_BASIS_POINTS_INHERIT`(`65535`)를 저장합니다. 컬렉션에는 `Royalties` 플러그인이 있어야 합니다. [컬렉션에서 로열티 상속](#inheriting-royalties-from-the-collection)을 참조하세요. ## Glossary @@ -187,6 +231,7 @@ const assetId = leaf.id; |------|------------| | **mintV2** | The Bubblegum V2 instruction for minting compressed NFTs, replacing the V1 mint instructions | | **MetadataArgsV2** | The metadata structure passed to mintV2, containing name, URI, royalties, collection, and creators | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | Sentinel value `65535` (`0xffff`) stored on-chain to indicate royalties are inherited from the MPL-Core collection | | **Collection Authority** | The signer authorized to manage the MPL-Core collection — required when minting to a collection | | **BubblegumV2 Plugin** | An MPL-Core collection plugin that enables Bubblegum V2 features (freeze, soulbound, royalties) | | **Asset ID** | A PDA derived from the merkle tree address and leaf index, uniquely identifying a compressed NFT | diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties.md b/src/pages/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties.md new file mode 100644 index 000000000..14c03e76c --- /dev/null +++ b/src/pages/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties.md @@ -0,0 +1,164 @@ +--- +title: 상속 로열티 읽기 +metaTitle: 상속 로열티 읽기 - Bubblegum V2 - Metaplex +description: 지갑, 마켓플레이스, 인덱서 및 기타 클라이언트가 MPL-Core 컬렉션에서 판매자 수수료를 상속하는 Bubblegum V2 cNFT에 대해 DAS getAsset 응답을 읽는 방법입니다. +created: '07-16-2026' +updated: '08-06-2026' +keywords: + - inherited royalties + - seller fee basis points + - DAS API + - getAsset + - basis_points_raw + - creators_raw + - inherited + - Bubblegum V2 +about: + - Compressed NFTs + - DAS API + - Royalties +proficiencyLevel: Intermediate +programmingLanguage: + - JavaScript + - TypeScript +faqs: + - q: royalty.basis_points_raw가 65535로 표시되는 이유는 무엇인가요? + a: 리프 해싱에 사용되는 온체인 상속 센티널입니다. royalty.basis_points에는 이미 표시용 컬렉션 비율이 들어 있습니다. + - q: 상속된 cNFT에서 creators_raw가 비어 있는 이유는 무엇인가요? + a: SFBP가 상속될 때 리프 creators는 비어 있어야 합니다. 컬렉션 로열티 수취인은 creators를 사용하세요. + - q: 상속하지 않는 cNFT에 대해 변경이 필요한가요? + a: 아니요. 상속을 사용하지 않으면 _raw 필드와 inherited는 생략되며 주요 royalty 및 creators 필드는 이전과 동일하게 동작합니다. +--- + +## 요약 + +Bubblegum V2는 리프에 **상속 센티널**(`65535`)로 판매자 수수료를 저장하고, MPL-Core 컬렉션의 Royalties 플러그인에서 실효 비율을 해석할 수 있습니다. DAS는 **컬렉션에서 해석된 값을 주 필드에 두고**(표시용), 리프 값은 `_raw` 필드에 노출합니다(해싱용). + +- **주 필드**(`royalty.basis_points`, `creators`)는 로열티 UI 및 지급 표시에 사용 +- **`_raw` 필드**(`royalty.basis_points_raw`, `creators_raw`)는 증명, 해싱, 쓰기 명령에 사용 +- 상속하지 않는 자산은 변경되지 않음 — `_raw` / `inherited`는 생략됨 + +이 페이지는 `getAsset` / DAS 응답을 **읽는** 모든 클라이언트(지갑, 마켓플레이스, 인덱서, 분석 도구, 앱)를 위한 것입니다. 상속 로열티 cNFT를 민팅하거나 업데이트하려면 [민팅](/ko/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection) 및 [업데이트](/ko/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)를 참조하세요. + +## 적용 시점 + +다음 조건을 만족하면 cNFT가 상속 로열티를 사용 중입니다. + +- `Royalties` 플러그인이 있는 MPL-Core 컬렉션의 Bubblegum V2 자산이고 +- 리프 판매자 수수료가 상속 센티널 `65535`(`0xffff`)인 경우 + +컬렉션 로열티를 주 필드에 해석할 수 있을 때 DAS는 `royalty.inherited: true`와 `royalty.basis_points_raw: 65535`로 이를 표시합니다. + +## 필드 맵 + +| 용도 | 필드 | +|------|------| +| 표시 비율 / 로열티 UI | `royalty.basis_points`, `royalty.percent` | +| 수취인 표시 / 지급 분할 | `creators` | +| 해싱, 머클 증명, 쓰기 명령 | `royalty.basis_points_raw`, `creators_raw` | +| 상속 모드 감지 | `royalty.inherited` (또는 `basis_points_raw === 65535`) | + +### 예시 DAS 응답 (상속) + +```json +"royalty": { + "royalty_model": "creators", + "target": null, + "percent": 0.075, + "basis_points": 750, + "basis_points_raw": 65535, + "inherited": true, + "primary_sale_happened": false, + "locked": false +}, +"creators": [ + { + "address": "CJkzXwVwqiaSvMuRb3obrZHdrPFjCMBJBDrjspn72tDv", + "share": 100, + "verified": true + } +], +"creators_raw": [] +``` + +- `basis_points: 750`은 사용자에게 보여줄 컬렉션 비율(7.5%)입니다. +- `basis_points_raw: 65535`는 리프 데이터 해시에 사용되는 온체인 센티널이며 — **655.35% 로열티가 아닙니다**. +- `creators`는 컬렉션 Royalties 플러그인 수취인이고, `creators_raw: []`는 해싱용 리프 creators 배열입니다. + +컬렉션을 해석할 수 없으면 `basis_points`가 폴백될 수 있지만 `basis_points_raw`는 `65535`로 유지됩니다. + +## 감지 및 표시 헬퍼 + +```ts +const INHERIT = 0xffff // 65535 + +function isInheritedRoyalty(royalty: { + basis_points: number + basis_points_raw?: number | null + inherited?: boolean | null +}): boolean { + return ( + royalty.inherited === true || + royalty.basis_points_raw === INHERIT + ) +} + +function leafBasisPoints(royalty: { + basis_points: number + basis_points_raw?: number | null + inherited?: boolean | null +}): number { + if (royalty.basis_points_raw != null) return royalty.basis_points_raw + if (royalty.inherited) return INHERIT + return royalty.basis_points +} + +function leafCreators(asset: { + creators: Array<{ address: string; share: number; verified: boolean }> + creators_raw?: Array<{ + address: string + share: number + verified: boolean + }> | null +}) { + return asset.creators_raw ?? asset.creators +} +``` + +`@metaplex-foundation/digital-asset-standard-api` 사용: + +```ts +import { + SELLER_FEE_BASIS_POINTS_INHERIT, + isInheritedSfbpRoyalty, + getRawSellerFeeBasisPoints, + getResolvedSellerFeeBasisPoints, +} from '@metaplex-foundation/digital-asset-standard-api' + +const royalty = asset.royalty +if (isInheritedSfbpRoyalty(royalty)) { + const rate = getResolvedSellerFeeBasisPoints(royalty) // e.g. 750 (display) + const leaf = getRawSellerFeeBasisPoints(royalty) // 65535 + const payees = asset.creators // collection payees + const leafCreators = asset.creators_raw ?? [] +} +``` + +## 하지 말아야 할 것 + +- `65535` 또는 `6.5535%`를 사용자용 로열티 비율로 **표시하지 마세요** — 그 값은 `basis_points_raw`에 있습니다. +- 빈 `creators_raw`가 로열티 수취인이 없음을 의미한다고 **가정하지 마세요**; 표시용 수취인은 `creators`에 있습니다. +- 리프 해시를 다시 계산하거나 Bubblegum 쓰기 명령을 구성할 때 주 필드의 `basis_points` / `creators`를 **사용하지 마세요** — `basis_points_raw`와 `creators_raw`를 사용하세요. + +## Bubblegum SDK 참고 + +`getAssetWithProof`는 쓰기 명령이 올바르게 해시되도록 DAS의 **리프** 필드(`basis_points_raw`, `creators_raw`)에서 `metadata`를 구성합니다. `getAssetWithProof` 이후 UI 비율이 필요하면 `rpcAsset.royalty.basis_points`와 `rpcAsset.creators`를 읽으세요. [JavaScript SDK](/ko/smart-contracts/bubblegum-v2/sdk/javascript#getassetwithproof-and-inherited-royalties)를 참조하세요. + +## 관련 + +- [압축 NFT 가져오기](/ko/smart-contracts/bubblegum-v2/fetch-cnfts) +- [민팅 — 로열티 상속](/ko/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection) +- [cNFT 업데이트 — 상속 로열티](/ko/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties) +- [NFT 데이터 해싱](/ko/smart-contracts/bubblegum-v2/hashed-nft-data) +- [DAS getAsset](/ko/dev-tools/das-api/methods/get-asset) +- [FAQ — 상속 로열티](/ko/smart-contracts/bubblegum-v2/faq#inherited-royalties) diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/sdk/javascript.md b/src/pages/ko/smart-contracts/bubblegum-v2/sdk/javascript.md index 9dfd02a3c..04f35ad86 100644 --- a/src/pages/ko/smart-contracts/bubblegum-v2/sdk/javascript.md +++ b/src/pages/ko/smart-contracts/bubblegum-v2/sdk/javascript.md @@ -3,7 +3,7 @@ title: JavaScript SDK metaTitle: JavaScript SDK - Bubblegum V2 - Metaplex description: Metaplex Bubblegum V2 JavaScript SDK의 완전한 참조 문서. Umi 설정, 트리 생성, 민팅, 전송, 소각, 업데이트, 위임, 동결, 압축 NFT 가져오기를 다룹니다. created: '2025-01-15' -updated: '2026-02-25' +updated: '06-19-2026' keywords: - mpl-bubblegum JavaScript - Bubblegum V2 TypeScript SDK @@ -39,7 +39,7 @@ faqs: - q: 이 SDK를 Bubblegum V1 트리와 함께 사용할 수 있나요? a: 아니요. 이 SDK는 LeafSchemaV2를 사용하는 Bubblegum V2를 대상으로 합니다. V1 트리에는 레거시 Bubblegum SDK를 사용하세요. - q: getAssetWithProof는 무엇이고 왜 필요한가요? - a: getAssetWithProof는 DAS API에서 리프 변경 명령에 필요한 모든 파라미터(증명, 루트, 리프 인덱스, 논스, 메타데이터)를 한 번의 호출로 가져오는 헬퍼입니다. 거의 모든 쓰기 명령에 이것이 필요합니다. + a: getAssetWithProof는 DAS API에서 리프 변경 명령에 필요한 모든 파라미터(증명, 루트, 리프 인덱스, 논스, 메타데이터)를 한 번의 호출로 가져오는 헬퍼입니다. 상속 로열티의 경우 metadata.sellerFeeBasisPoints는 온체인 리프 센티널(65535)이며, 해석된 컬렉션 비율은 rpcAsset.royalty.basis_points에 있습니다. --- **Bubblegum V2 JavaScript SDK**(`@metaplex-foundation/mpl-bubblegum`)는 Solana에서 [압축 NFT](/ko/smart-contracts/bubblegum-v2)를 생성하고 관리하기 위한 권장 TypeScript/JavaScript 라이브러리입니다. [Umi 프레임워크](/ko/dev-tools/umi)를 기반으로 구축되었으며, 모든 Bubblegum V2 작업에 대한 타입 안전 함수를 제공하고 [DAS API](/ko/smart-contracts/bubblegum-v2/fetch-cnfts) 플러그인이 자동으로 포함됩니다. {% .lead %} @@ -197,6 +197,14 @@ await mintV2(umi, { }).sendAndConfirm(umi) ``` +### 컬렉션에서 로열티 상속 + +`coreCollection`이 설정되면 SDK의 `mintV2` 헬퍼는 `metadata.sellerFeeBasisPoints`가 생략된 경우 상속 로열티를 기본값으로 사용합니다. 리프에는 `SELLER_FEE_BASIS_POINTS_INHERIT`(`65535`)가 저장됩니다. 컬렉션에는 `Royalties` 플러그인이 필요하고 `metadata.creators`는 비어 있어야 합니다. + +{% code-tabs-imported from="bubblegum/mint-inherit-royalties" frameworks="umi" /%} + +컬렉션 설정 및 제약은 [압축 NFT 민팅 — 로열티 상속](/ko/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)을 참조하세요. + ### 민팅 후 에셋 ID 가져오기 민트가 확인된 후 `parseLeafFromMintV2Transaction`을 사용하여 리프 스키마(에셋 ID 포함)를 가져옵니다. @@ -276,13 +284,26 @@ const updateArgs: UpdateArgsArgs = { await updateMetadataV2(umi, { ...assetWithProof, leafOwner: assetWithProof.leafOwner, - currentMetadata: assetWithProof.metadata, + // 기존 리프 메타데이터의 명령 인자 이름(V2 collection은 pubkey). + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(publicKey('YourCollectionAddressHere')), + }, updateArgs, // If cNFT belongs to a collection, pass the collection address: coreCollection: publicKey('YourCollectionAddressHere'), }).sendAndConfirm(umi) ``` +`getAssetWithProof.metadata`는 항상 리프를 미러링합니다(상속 로열티 시 `65535` 포함). 표시용으로는 `rpcAsset.royalty.basis_points`와 `rpcAsset.creators`를 읽으세요. + ## 압축 NFT 위임 {% #delegate-a-compressed-nft %} [리프 위임자](/ko/smart-contracts/bubblegum-v2/delegate-cnfts)는 소유자를 대신하여 cNFT를 전송, 소각, 동결할 수 있습니다. 위임자는 전송 후 새로운 소유자로 초기화됩니다. @@ -484,6 +505,21 @@ await unverifyCreatorV2(umi, { DAS API 플러그인은 `mplBubblegum()`에 의해 자동으로 등록됩니다. 사용 가능한 메서드의 전체 설명은 [cNFT 가져오기](/ko/smart-contracts/bubblegum-v2/fetch-cnfts)를 참조하세요. +### getAssetWithProof and inherited royalties {% #getassetwithproof-and-inherited-royalties %} + +`getAssetWithProof`는 `getAsset`과 `getAssetProof`를 쓰기 명령이 예상하는 파라미터 형태로 결합합니다. + +| Field | Purpose | +|-------|---------| +| `metadata` | 해싱 및 쓰기 명령용 리프 정규 메타데이터(`basis_points_raw` / `creators_raw`에서 구성). 로열티가 상속된 경우 `sellerFeeBasisPoints`는 `65535`이고 `creators`는 리프 크리에이터 목록(보통 비어 있음)입니다. | +| `rpcAsset` | 전체 DAS 응답. 컬렉션에서 해석된 표시 값은 `royalty.basis_points`, `royalty.percent`, `creators`에 있고, 리프 값은 `royalty.basis_points_raw`와 `creators_raw`에 있습니다. | + +`updateMetadataV2`는 기존 리프 인자 이름을 여전히 `currentMetadata`(IDL)로 둡니다. V2 `collection`을 pubkey로 하여 `assetWithProof.metadata` 리프 필드에서 해당 `MetadataArgsV2`를 구성하세요. + +DAS를 직접 읽는 클라이언트는 [상속 로열티 읽기](/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties)를 따르세요. + +{% code-tabs-imported from="bubblegum/get-asset-with-proof-inherited" frameworks="umi" /%} + ### 단일 cNFT 가져오기 ```ts {% title="fetch-asset.ts" %} @@ -606,7 +642,8 @@ RPC 제공자가 Metaplex DAS API를 지원하지 않을 수 있습니다. [호 | `setNonTransferableV2` | cNFT를 영구적으로 소울바운드로 만들기 (되돌릴 수 없음) | | `verifyCreatorV2` | 크리에이터 항목에 verified 플래그 설정 | | `unverifyCreatorV2` | 크리에이터 항목에서 verified 플래그 제거 | -| `getAssetWithProof` | 쓰기 명령에 필요한 모든 증명 파라미터 가져오기 | +| `getAssetWithProof` | 증명 파라미터 가져오기; `metadata`는 리프 정규 값, 표시용 상속 값은 `rpcAsset`에 있음 | +| `SELLER_FEE_BASIS_POINTS_INHERIT` | MPL-Core 컬렉션에서 상속된 로열티의 센티널 상수(`65535`) | | `findLeafAssetIdPda` | 트리 주소와 리프 인덱스에서 cNFT 에셋 ID 도출 | | `parseLeafFromMintV2Transaction` | 민트 트랜잭션에서 리프 스키마 (에셋 ID 포함) 추출 | diff --git a/src/pages/ko/smart-contracts/bubblegum-v2/update-cnfts.md b/src/pages/ko/smart-contracts/bubblegum-v2/update-cnfts.md index a9af2091e..62c5d8674 100644 --- a/src/pages/ko/smart-contracts/bubblegum-v2/update-cnfts.md +++ b/src/pages/ko/smart-contracts/bubblegum-v2/update-cnfts.md @@ -3,7 +3,7 @@ title: 압축된 NFT 업데이트 metaTitle: 압축된 NFT 업데이트 - Bubblegum V2 description: Bubblegum에서 압축된 NFT를 업데이트하는 방법을 알아보세요. created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - update compressed NFT - update cNFT @@ -24,6 +24,8 @@ faqs: a: UpdateArgsArgs에 정의된 이름, URI, 판매자 수수료 기준 포인트 및 기타 메타데이터 필드를 업데이트할 수 있습니다. 변경하려는 필드에는 some('newValue')을 사용하세요. - q: 업데이트 시 컬렉션을 전달해야 하나요? a: 예, cNFT가 컬렉션에 속한 경우. 컬렉션의 공개 키와 함께 coreCollection 매개변수를 전달하세요. 컬렉션 권한이 트랜잭션에 서명해야 합니다. + - q: 컬렉션에서 로열티를 상속하는 cNFT를 업데이트하려면 어떻게 해야 하나요? + a: getAssetWithProof의 리프 메타데이터를 updateMetadataV2의 currentMetadata 인자(기존 리프 상태에 대한 IDL 이름)로 전달하세요. 로열티가 상속된 경우 sellerFeeBasisPoints는 온체인 센티널입니다. --- ## Summary @@ -34,6 +36,7 @@ faqs: - Collection authority updates cNFTs that belong to a collection - Tree authority updates cNFTs that do not belong to a collection - Changes are reflected in the merkle tree and indexed by DAS API providers +- `getAssetWithProof`의 리프 메타데이터를 `updateMetadataV2`의 `currentMetadata` 인자(기존 리프 상태에 대한 IDL 이름)로 사용 **updateMetadataV2** 명령어는 압축된 NFT의 메타데이터를 수정하는 데 사용할 수 있습니다. 머클 루트가 업데이트되어 데이터의 전파된 해시를 반영하고, [Metaplex DAS API](https://github.com/metaplex-foundation/digital-asset-standard-api)를 준수하는 RPC 제공업체는 cNFT의 인덱스를 업데이트합니다. @@ -90,7 +93,17 @@ const updateArgs: UpdateArgsArgs = { await updateMetadataV2(umi, { ...assetWithProof, leafOwner, - currentMetadata: assetWithProof.metadata, + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(publicKey('22222222222222222222222222222222')), + }, updateArgs, // 선택적 매개변수. 권한이 현재 umi 신원과 다른 서명자 타입인 경우 // 여기에 해당 서명자를 할당합니다. @@ -100,6 +113,22 @@ await updateMetadataV2(umi, { }).sendAndConfirm(umi) ``` +{% callout type="note" title="쓰기 명령용 리프 메타데이터" %} +`getAssetWithProof.metadata`는 항상 리프 정규 값입니다 — 로열티가 상속된 경우 `sellerFeeBasisPoints: 65535` 포함. 컬렉션에서 해석된 표시 값은 `rpcAsset.royalty.basis_points`와 `rpcAsset.creators`에 있습니다. + +`updateMetadataV2`의 `currentMetadata` 인자는 기존 리프 메타데이터의 IDL 이름입니다(V2 형태: `collection`은 pubkey). `assetWithProof.metadata`에서 구성하세요. + +자산을 읽을 때 DAS 응답 필드 안내는 [상속 로열티 읽기](/ko/smart-contracts/bubblegum-v2/reading-inherited-royalties)를 참조하세요. +{% /callout %} + +## 상속된 로열티 {% #inherited-royalties %} + +`updateArgs.sellerFeeBasisPoints`를 `some(SELLER_FEE_BASIS_POINTS_INHERIT)`로 설정하면 cNFT를 상속 로열티**로** 전환할 수 있습니다. 컬렉션에는 `Royalties` 플러그인이 있어야 하며 업데이트된 메타데이터의 `creators` 배열은 비어 있어야 합니다. + +상속 로열티**에서** 명시적인 비율로 되돌리려면 — 예를 들어 [cNFT를 컬렉션에서 제거하기](/ko/smart-contracts/bubblegum-v2/collections#inherited-royalties) 전에 — 원하는 basis points를 전달하세요: + +{% code-tabs-imported from="bubblegum/update-inherit-royalties" frameworks="umi" /%} + {% /totem %} {% /dialect %} {% /dialect-switcher %} @@ -107,12 +136,27 @@ await updateMetadataV2(umi, { ## Notes - The update authority depends on whether the cNFT belongs to a collection. Collection cNFTs use the collection authority; standalone cNFTs use the tree authority. -- You must pass `currentMetadata` from `getAssetWithProof` so the program can verify the current leaf before applying updates. +- 프로그램이 업데이트를 적용하기 전에 현재 리프를 검증할 수 있도록 `getAssetWithProof`의 리프 메타데이터를 `updateMetadataV2`의 `currentMetadata` 인자로 전달하세요. - Use `some()` for fields you want to update and omit fields you want to keep unchanged. +- Inherited seller fees require an empty leaf-level `creators` array and a collection with the `Royalties` plugin. ## FAQ -# +### 압축된 NFT의 메타데이터를 업데이트할 수 있는 사람은 누구인가요? + +cNFT가 컬렉션에 속한 경우 컬렉션 권한만 업데이트할 수 있습니다. 컬렉션에 속하지 않은 경우 트리 권한(트리 생성자 또는 위임자)이 업데이트할 수 있습니다. + +### cNFT에서 업데이트할 수 있는 필드는 무엇인가요? + +`UpdateArgsArgs`에 정의된 이름, URI, seller fee basis points 및 기타 메타데이터 필드를 업데이트할 수 있습니다. 변경하려는 필드에는 `some('newValue')`를 사용하세요. + +### 업데이트 시 컬렉션을 전달해야 하나요? + +예, cNFT가 컬렉션에 속한 경우. 컬렉션의 공개 키와 함께 `coreCollection` 매개변수를 전달하세요. 컬렉션 권한이 트랜잭션에 서명해야 합니다. + +### 컬렉션에서 로열티를 상속하는 cNFT를 업데이트하려면 어떻게 해야 하나요? + +검증에 온체인 센티널이 사용되도록 `getAssetWithProof`의 리프 메타데이터를 `updateMetadataV2`의 `currentMetadata` 인자로 전달하세요. 상속 로열티로 전환하려면 `updateArgs.sellerFeeBasisPoints`에 `some(SELLER_FEE_BASIS_POINTS_INHERIT)`를, 전환하려면 명시적인 숫자를 사용하세요. ## Glossary @@ -122,4 +166,5 @@ await updateMetadataV2(umi, { | **Collection Authority** | The update authority of the MPL-Core collection, authorized to update cNFTs in that collection | | **Tree Authority** | The tree creator or delegate, authorized to update cNFTs that do not belong to a collection | | **UpdateArgsArgs** | The TypeScript type defining which metadata fields to update, using Option wrappers | -| **currentMetadata** | The existing metadata of the cNFT, fetched via getAssetWithProof and required for verification | +| **currentMetadata** | 기존 리프 메타데이터에 대한 `updateMetadataV2`의 IDL 인자; `getAssetWithProof.metadata`에서 구성 | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | Sentinel value `65535` indicating royalties are inherited from the MPL-Core collection | diff --git a/src/pages/zh/dev-tools/das-api/methods/get-asset.md b/src/pages/zh/dev-tools/das-api/methods/get-asset.md index a0072487b..729814b6f 100644 --- a/src/pages/zh/dev-tools/das-api/methods/get-asset.md +++ b/src/pages/zh/dev-tools/das-api/methods/get-asset.md @@ -7,6 +7,8 @@ tableOfContents: false 返回压缩/标准资产的信息，包括元数据和所有者。 +对于从 MPL-Core 集合继承卖家费用的 Bubblegum V2 cNFT，集合解析后的展示值位于 `royalty.basis_points` / `creators`，叶子值位于 `royalty.basis_points_raw` / `creators_raw`（同时 `royalty.inherited: true`）。请参阅[读取继承版税](/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties)。 + ## 参数 | 名称 | 必需 | 描述 | diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/collections.md b/src/pages/zh/smart-contracts/bubblegum-v2/collections.md index af12f789a..29550116c 100644 --- a/src/pages/zh/smart-contracts/bubblegum-v2/collections.md +++ b/src/pages/zh/smart-contracts/bubblegum-v2/collections.md @@ -3,7 +3,7 @@ title: 管理集合 metaTitle: 管理集合 - Bubblegum V2 description: 了解如何在Bubblegum上设置、验证和取消验证集合。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - NFT collection - verify collection @@ -26,6 +26,8 @@ faqs: a: 可以。使用带有coreCollection（当前）和newCoreCollection（新）两个参数的setCollectionV2。两个集合权限都必须签名。 - q: BubblegumV2插件是什么？ a: 它是一个MPL-Core集合插件，在集合上启用Bubblegum V2功能，如冻结/解冻、灵魂绑定cNFT和版税强制执行。 + - q: 继承版税的cNFT可以从集合中移除吗？ + a: 不可以。请先将sellerFeeBasisPoints更新为明确值，然后使用setCollectionV2移除集合。 --- ## Summary @@ -118,15 +120,38 @@ const signature = await setCollectionV2(umi, { {% /dialect %} {% /dialect-switcher %} +## 继承版税 {% #inherited-royalties %} + +通过[从集合继承 seller fee basis points](/zh/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)铸造的 cNFT 会在叶子上存储哨兵值 `65535`。这会影响集合管理： + +- **移除集合** — 当叶子仍使用继承哨兵时，`setCollectionV2` 会拒绝该操作。请先通过 [`updateMetadataV2`](/zh/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties) 将 cNFT 的 `sellerFeeBasisPoints` 更新为明确值。 +- **移动到另一个集合** — 当目标集合具有 `Royalties` 插件时允许。cNFT 保留继承哨兵并从新集合解析版税。 +- **移动到没有版税的集合** — 会被 `CollectionMustHaveRoyaltiesPlugin` 拒绝。 + ## Notes - The MPL-Core collection must have the `BubblegumV2` plugin enabled before cNFTs can be added to it. - Unlike Bubblegum V1 (which uses Token Metadata collections with a "verified" boolean), V2 uses MPL-Core collections without verification flags. - When changing between collections, both the old and new collection authorities must sign the transaction. +- 继承 seller fee 的 cNFT 在叶子上的版税设置为明确值之前，无法从集合中移除。 ## FAQ -# +### 铸造后如何将 cNFT 添加到集合中？ + +使用 `setCollectionV2` 指令，并将 `newCoreCollection` 参数设置为集合的公钥。集合权限必须签名。 + +### 可以更改 cNFT 的集合吗？ + +可以。使用 `setCollectionV2` 并同时传入 `coreCollection`（当前）和 `newCoreCollection`（新）参数。如果权限是不同的账户，两个集合权限都必须签名。 + +### BubblegumV2 插件是什么？ + +它是一个 MPL-Core 集合插件，在集合级别启用 Bubblegum V2 功能，如冻结/解冻、灵魂绑定 cNFT、版税强制执行和永久委托。 + +### 继承版税的 cNFT 可以从集合中移除吗？ + +不可以。程序会返回 `CannotRemoveFromCollectionWithInheritedSellerFee`。请先用 `updateMetadataV2` 将 `sellerFeeBasisPoints` 设置为明确值，然后调用 `setCollectionV2` 移除集合。 ## Glossary diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/faq.md b/src/pages/zh/smart-contracts/bubblegum-v2/faq.md index f4f8d37c5..e0c3ccda2 100644 --- a/src/pages/zh/smart-contracts/bubblegum-v2/faq.md +++ b/src/pages/zh/smart-contracts/bubblegum-v2/faq.md @@ -3,7 +3,7 @@ title: 常见问题 metaTitle: 常见问题 - Bubblegum V2 description: 关于Bubblegum的常见问题。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - Bubblegum FAQ - compressed NFT questions @@ -35,6 +35,8 @@ faqs: a: 解压缩仅适用于Bubblegum V1资产。V2不支持解压缩。 - q: 一棵树可以存储多少个cNFT？ a: 最大值为2^maxDepth。深度为30的树可以容纳超过10亿个cNFT，但树越大租金成本越高。 + - q: cNFT可以从MPL-Core集合继承版税吗？ + a: 可以。铸造到具有Royalties插件的集合时，省略sellerFeeBasisPoints。叶子上存储继承哨兵（65535）；DAS将集合费率放在royalty.basis_points上，哨兵放在royalty.basis_points_raw上。写入指令请使用getAssetWithProof.metadata（叶子值）。 --- ## Summary @@ -45,6 +47,7 @@ faqs: - 使用`truncateCanopy`或地址查找表解决"交易过大"错误 - 创建树之前了解树的成本和容量 - Bubblegum V2与V1树或解压缩不向后兼容 +- cNFT可以从MPL-Core集合的Royalties插件继承seller fee basis points ## 什么是Bubblegum V2？ @@ -154,3 +157,30 @@ await transferV2(umi, { 另一种方法是实现[版本化交易和地址查找表](/zh/dev-tools/umi/toolbox/address-lookup-table)。此方法可以帮助更有效地管理交易大小。 通过应用这些技术，您可以克服交易大小限制并成功执行您的操作。 + +## 一棵树可以存储多少个cNFT？ {% #tree-capacity %} + +cNFT 的最大数量是 `2^maxDepth`。深度 14 的树可容纳 16,384 个，深度 20 约 100 万个，深度 24 约 1,600 万个，深度 30 超过 10 亿个。所有选项请参阅[树容量表](/zh/smart-contracts/bubblegum-v2/create-trees)。 + +## cNFT 可以从 MPL-Core 集合继承版税吗？ {% #inherited-royalties %} + +可以。铸造到具有 `Royalties` 插件的 MPL-Core 集合时，可以省略 `metadata.sellerFeeBasisPoints`（或传入 `SELLER_FEE_BASIS_POINTS_INHERIT`、`65535`）。叶子上链存储该哨兵值。DAS 将集合解析后的费率放在 `royalty.basis_points` / `creators` 上供展示，并将叶子哨兵放在 `royalty.basis_points_raw` / `creators_raw` 上（同时 `royalty.inherited: true`）。 + +**要求:** + +- 集合必须同时具有 `BubblegumV2` 和 `Royalties` 插件。 +- 使用继承 seller fee 时，`metadata.creators` 必须是空数组。 + +**使用 `getAssetWithProof`:** + +- **`metadata`** — 用于哈希和写入指令的叶子规范值（继承时 `sellerFeeBasisPoints` 为 `65535`）。 +- **`rpcAsset`** — 展示 / 分账 UI 请使用 `royalty.basis_points` 与 `creators`。 + +调用 `updateMetadataV2` 时，将叶子元数据作为指令的 `currentMetadata` 参数传入（IDL 中表示现有叶子状态的名称）。 + +**集合管理:** + +- 具有继承 seller fee 的 cNFT 在更新为明确的 `sellerFeeBasisPoints` 之前**无法**从集合中移除。 +- 当目标集合具有 `Royalties` 插件时，允许移动到另一个集合。 + +读取 DAS 的客户端请参阅[读取继承版税](/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties)；完整示例请参阅[铸造 — 继承版税](/zh/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)、[更新 cNFT](/zh/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)和[管理集合](/zh/smart-contracts/bubblegum-v2/collections#inherited-royalties)。 diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/fetch-cnfts.md b/src/pages/zh/smart-contracts/bubblegum-v2/fetch-cnfts.md index 414d7bbd6..8cffc89c8 100644 --- a/src/pages/zh/smart-contracts/bubblegum-v2/fetch-cnfts.md +++ b/src/pages/zh/smart-contracts/bubblegum-v2/fetch-cnfts.md @@ -208,6 +208,7 @@ const rpcAssetList = await umi.rpc.getAssetsByGroup({ - 并非所有RPC提供商都支持DAS API。请查看[RPC提供商](/zh/rpc-providers)页面获取兼容选项。 - 安装`mplBubblegum`时会自动包含DAS API插件，无需单独安装。 - 通过`getAssetProof`获取的证明在树被修改后可能会过期。在执行写入操作前始终获取最新证明。 +- 对于从集合继承卖家费用的 Bubblegum V2 cNFT，DAS 将集合费率放在 `royalty.basis_points` / `creators` 上，将叶子哨兵放在 `royalty.basis_points_raw` / `creators_raw` 上。请参阅[读取继承版税](/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties)。 ## Glossary diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/hashed-nft-data.md b/src/pages/zh/smart-contracts/bubblegum-v2/hashed-nft-data.md index 70c5f3f94..5384c824c 100644 --- a/src/pages/zh/smart-contracts/bubblegum-v2/hashed-nft-data.md +++ b/src/pages/zh/smart-contracts/bubblegum-v2/hashed-nft-data.md @@ -3,7 +3,7 @@ title: 哈希NFT数据 metaTitle: 哈希NFT数据 - Bubblegum V2 description: 了解更多关于Bubblegum上NFT数据如何被哈希的信息。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - hashed NFT data - merkle leaf @@ -281,7 +281,8 @@ pub struct MetadataArgsV2 { pub symbol: String, /// 指向代表资产的JSON的URI pub uri: String, - /// 二级销售中给予创作者的版税基点（0-10000） + /// 二级销售中给予创作者的版税基点（0-10000）， + /// 或 u16::MAX（65535）以从 MPL-Core 集合的 Royalties 插件继承。 pub seller_fee_basis_points: u16, /// 不可变，一旦翻转，此元数据的所有销售都被视为二级销售 pub primary_sale_happened: bool, @@ -296,6 +297,8 @@ pub struct MetadataArgsV2 { } ``` +当 `seller_fee_basis_points` 为 `65535`（`0xffff`，`SELLER_FEE_BASIS_POINTS_INHERIT`）时，叶子上存储的是哨兵值而非字面版税百分比。数据哈希根据该哨兵值计算，而非根据集合的已解析 basis points。DAS 将集合费率放在 `royalty.basis_points` 上，将叶子哨兵放在 `royalty.basis_points_raw` 上。JavaScript SDK 的 `getAssetWithProof` 辅助函数将叶子哨兵放在 `metadata.sellerFeeBasisPoints` 上。请参阅[读取继承版税](/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties)和[从集合继承版税](/zh/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)。 + cNFT的元数据被多次哈希，如图表所示并在下面描述： {% diagram %} @@ -523,6 +526,7 @@ impl LeafSchema { | Term | Definition | |------|------------| | **MetadataArgsV2** | The Rust struct containing cNFT metadata (name, symbol, URI, royalties, creators, collection) | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | 从 MPL-Core 集合继承版税时存储在 `seller_fee_basis_points` 中的哨兵值 `65535` | | **Data Hash** | keccak-256 hash of the metadata combined with seller_fee_basis_points | | **Creator Hash** | keccak-256 hash of the creator array (address, verified flag, share for each creator) | | **Collection Hash** | keccak-256 hash of the collection public key (new in V2) | diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/index.md b/src/pages/zh/smart-contracts/bubblegum-v2/index.md index 346ea4bbd..c05cffe19 100644 --- a/src/pages/zh/smart-contracts/bubblegum-v2/index.md +++ b/src/pages/zh/smart-contracts/bubblegum-v2/index.md @@ -3,7 +3,7 @@ title: 概述 metaTitle: 概述 - Bubblegum V2 description: 提供Bubblegum V2和压缩NFT的高级概述。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - compressed NFT - cNFT @@ -83,7 +83,8 @@ Bubblegum V2在原始Bubblegum程序的基础上构建，同时引入了几个 - **冻结和解冻功能**：提供两种类型的冻结/解冻：1）cNFT所有者可以将冻结权限委托给叶子委托人，用于资产级别的控制，为各种用例提供灵活性，如在特定事件期间阻止转账或实现锁定机制。2）如果在集合创建时启用了`PermanentFreezeDelegate`插件，项目创建者可以通过永久冻结委托人对cNFT进行集合级别的冻结和解冻控制 - **MPL-Core集合集成**：Bubblegum V2 NFT现在可以添加到MPL-Core集合，而不仅限于代币元数据集合，允许更大的灵活性和与更广泛的Metaplex生态系统的集成。 -- **版税强制执行**：由于Bubblegum V2使用[MPL-Core](https://docs.metaplex.com/core/overview)集合，可以使用`ProgramDenyList`等方式对cNFT强制执行版税。 +- **版税强制执行**：由于Bubblegum V2使用[MPL-Core](/zh/smart-contracts/core)集合，可以使用`ProgramDenyList`等方式对cNFT强制执行版税。 +- **继承版税**：铸造到 MPL-Core 集合的 cNFT 可以在叶子上存储哨兵 seller fee basis points 值（`65535`），并继承集合的 Royalties 插件配置，而无需在每次铸造时复制 basis points。 - **灵魂绑定NFT**：cNFT现在可以设为灵魂绑定（不可转让），将其永久绑定到所有者的钱包。这非常适合凭证、出席证明、身份验证等。它需要在创建集合时启用`PermanentFreezeDelegate`插件。 - **允许永久转账**：如果在集合上启用了`PermanentTransferDelegate`插件，永久转账委托人现在可以在没有叶子所有者交互的情况下将cNFT转移给新所有者。 - **授权销毁**：如果集合启用了`PermanentBurnDelegate`插件，委托人可以在没有叶子所有者签名的情况下销毁NFT。 diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/mint-cnfts.md b/src/pages/zh/smart-contracts/bubblegum-v2/mint-cnfts.md index 395f551f2..6709a1428 100644 --- a/src/pages/zh/smart-contracts/bubblegum-v2/mint-cnfts.md +++ b/src/pages/zh/smart-contracts/bubblegum-v2/mint-cnfts.md @@ -3,7 +3,7 @@ title: 铸造压缩NFT metaTitle: 铸造压缩NFT - Bubblegum V2 description: 了解如何在Bubblegum V2上铸造压缩NFT。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - mint compressed NFT - mint cNFT @@ -29,6 +29,8 @@ faqs: a: 只有在树设置为公开时才可以。对于私有树，只有树创建者或树委托人才能铸造。 - q: 铸造需要哪些元数据字段？ a: MetadataArgsV2需要name、uri、sellerFeeBasisPoints、collection（或none）以及creators数组。 + - q: cNFT可以从MPL-Core集合继承版税吗？ + a: 可以。铸造到具有Royalties插件的集合时，可省略sellerFeeBasisPoints（或传入SELLER_FEE_BASIS_POINTS_INHERIT哨兵）。叶子上存储65535（0xffff）；DAS将集合费率放在royalty.basis_points上，哨兵放在royalty.basis_points_raw上。 --- ## Summary @@ -39,6 +41,7 @@ faqs: - Mint directly into an MPL-Core collection with the BubblegumV2 plugin - Retrieve the asset ID and leaf schema from the mint transaction - Configure metadata including name, URI, creators, and royalties +- 从 MPL-Core 集合的 Royalties 插件继承 seller fee basis points 在[上一页](/zh/smart-contracts/bubblegum-v2/create-trees)中，我们看到需要一个Bubblegum树来铸造压缩NFT，以及如何创建一个。现在，让我们看看如何从给定的Bubblegum树铸造压缩NFT。{% .lead %} @@ -142,6 +145,28 @@ await createCollection(umi, { {% /dialect %} {% /dialect-switcher %} +## 从集合继承版税 + +铸造到 MPL-Core 集合时，可以在叶子上存储**哨兵** seller fee basis points 值（`65535`，导出为 `SELLER_FEE_BASIS_POINTS_INHERIT` / `0xffff`），而不是将集合的版税百分比复制到每个 cNFT。DAS 将集合解析后的费率放在 `royalty.basis_points` / `creators` 上供展示，并将叶子哨兵放在 `royalty.basis_points_raw` / `creators_raw` 上（同时 `royalty.inherited: true`），而链上叶子为哈希保留哨兵值。 + +**读取** DAS 响应的客户端（钱包、市场、索引器与应用）应遵循[读取继承版税](/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties)。 + +当提供了 `coreCollection` 且省略 `metadata.sellerFeeBasisPoints` 时，JavaScript SDK 的 `mintV2` 辅助函数默认使用此行为。 + +**要求:** + +- MPL-Core 集合必须同时具有 `BubblegumV2` 和 `Royalties` 插件。 +- 使用继承 seller fee 时，`metadata.creators` 必须是**空数组**。创作者分配来自集合的 Royalties 插件，而非叶子级创作者。 +- 继承 seller fee 仅对集合中的 cNFT 有效。无集合铸造必须使用 `0` 到 `10000` 之间的明确值。 + +{% code-tabs-imported from="bubblegum/mint-inherit-royalties" frameworks="umi" /%} + +你仍可以传入明确的 `sellerFeeBasisPoints` 以覆盖单次铸造的集合默认值。 + +{% callout type="note" title="移除集合" %} +具有继承 seller fee 的 cNFT 在 seller fee 更新为明确值之前无法从集合中移除。请参阅[管理集合](/zh/smart-contracts/bubblegum-v2/collections#inherited-royalties)和[更新压缩 NFT](/zh/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)。 +{% /callout %} + ### 从铸造交易获取资产ID和叶子模式 {% #get-leaf-schema-from-mint-transaction %} 您可以使用`parseLeafFromMintV2Transaction`辅助函数从`mintV2`交易中检索叶子并确定资产ID。此函数解析交易，因此您必须确保在调用`parseLeafFromMintV2Transaction`之前交易已完成。 @@ -174,12 +199,31 @@ const assetId = leaf.id; - The Bubblegum Tree must be created before minting. See [Creating Trees](/smart-contracts/bubblegum-v2/create-trees). - For collection mints, the MPL-Core collection must have the `BubblegumV2` plugin enabled. +- 要从集合继承版税，集合还必须具有 `Royalties` 插件，且叶子的 `creators` 数组必须为空。 - The collection authority must sign the transaction when minting to a collection, regardless of whether the tree is public or private. - Use `parseLeafFromMintV2Transaction` only after the transaction is **finalized**, not just confirmed. ## FAQ -# +### 如何将压缩 NFT 铸造到集合中？ + +使用 `mintV2` 指令，将 `coreCollection` 参数设置为 MPL-Core 集合地址，并提供 `collectionAuthority` 签名者。集合必须启用 `BubblegumV2` 插件。 + +### 铸造后如何获取资产 ID？ + +在交易完成后使用 `parseLeafFromMintV2Transaction` 辅助函数。它会解析交易并通过 `leaf.id` 返回包含资产 ID 的叶子模式。 + +### 任何人都可以从我的树铸造吗？ + +仅当树以 `public: true` 创建时才可以。对于私有树，只有树创建者或树委托人可以铸造 cNFT。 + +### 铸造需要哪些元数据字段？ + +`MetadataArgsV2` 结构体需要：`name`（字符串）、`uri`（指向 JSON 元数据的字符串）、`sellerFeeBasisPoints`（0-10000，或铸造到集合时省略以从其 Royalties 插件继承）、`collection`（公钥或 none）、`creators`（创作者对象数组；继承版税时必须为空）。 + +### cNFT 可以从 MPL-Core 集合继承版税吗？ + +可以。使用 `coreCollection` 铸造时，省略 `metadata.sellerFeeBasisPoints` 并将 `metadata.creators` 留空。SDK 在叶子上存储 `SELLER_FEE_BASIS_POINTS_INHERIT`（`65535`）。集合必须具有 `Royalties` 插件。请参阅[从集合继承版税](#inheriting-royalties-from-the-collection)。 ## Glossary @@ -187,6 +231,7 @@ const assetId = leaf.id; |------|------------| | **mintV2** | The Bubblegum V2 instruction for minting compressed NFTs, replacing the V1 mint instructions | | **MetadataArgsV2** | The metadata structure passed to mintV2, containing name, URI, royalties, collection, and creators | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | Sentinel value `65535` (`0xffff`) stored on-chain to indicate royalties are inherited from the MPL-Core collection | | **Collection Authority** | The signer authorized to manage the MPL-Core collection — required when minting to a collection | | **BubblegumV2 Plugin** | An MPL-Core collection plugin that enables Bubblegum V2 features (freeze, soulbound, royalties) | | **Asset ID** | A PDA derived from the merkle tree address and leaf index, uniquely identifying a compressed NFT | diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties.md b/src/pages/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties.md new file mode 100644 index 000000000..5dde84791 --- /dev/null +++ b/src/pages/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties.md @@ -0,0 +1,164 @@ +--- +title: 读取继承版税 +metaTitle: 读取继承版税 - Bubblegum V2 - Metaplex +description: 钱包、市场、索引器及其他客户端应如何读取 DAS getAsset 响应，以处理从 MPL-Core 集合继承卖家费用的 Bubblegum V2 cNFT。 +created: '07-16-2026' +updated: '08-06-2026' +keywords: + - inherited royalties + - seller fee basis points + - DAS API + - getAsset + - basis_points_raw + - creators_raw + - inherited + - Bubblegum V2 +about: + - Compressed NFTs + - DAS API + - Royalties +proficiencyLevel: Intermediate +programmingLanguage: + - JavaScript + - TypeScript +faqs: + - q: 为什么 royalty.basis_points_raw 显示为 65535？ + a: 那是链上用于叶子哈希的继承哨兵值。royalty.basis_points 已包含用于展示的集合费率。 + - q: 为什么继承版税的 cNFT 上 creators_raw 为空？ + a: 当 SFBP 被继承时，叶子上的 creators 必须为空。请使用 creators 获取集合版税收款方。 + - q: 对于非继承版税的 cNFT，我需要改什么吗？ + a: 不需要。未使用继承时，_raw 字段与 inherited 会被省略，主要的 royalty 与 creators 字段行为与之前相同。 +--- + +## 摘要 + +Bubblegum V2 可以在叶子上以**继承哨兵**（`65535`）存储卖家费用，并从 MPL-Core 集合的 Royalties 插件解析有效费率。DAS 将**集合解析后的值放在主字段上**（用于展示），并在 `_raw` 字段上暴露叶子值（用于哈希）。 + +- 使用**主字段**（`royalty.basis_points`、`creators`）进行版税 UI 与分账展示 +- 使用 **`_raw` 字段**（`royalty.basis_points_raw`、`creators_raw`）进行证明、哈希和写入指令 +- 非继承资产保持不变 — `_raw` / `inherited` 会被省略 + +本页面向任何**读取** `getAsset` / DAS 响应的客户端 — 钱包、市场、索引器、分析工具与应用。关于铸造与更新继承版税的 cNFT，请参阅[铸造](/zh/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)与[更新](/zh/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties)。 + +## 何时适用 + +当满足以下条件时，cNFT 正在使用继承版税： + +- 它是位于带有 `Royalties` 插件的 MPL-Core 集合中的 Bubblegum V2 资产，并且 +- 叶子上的卖家费用为继承哨兵 `65535`（`0xffff`） + +当可以将集合版税解析到主字段时，DAS 会以 `royalty.inherited: true` 和 `royalty.basis_points_raw: 65535` 表明这一点。 + +## 字段对照表 + +| 用例 | 字段 | +|------|------| +| 展示费率 / 版税 UI | `royalty.basis_points`、`royalty.percent` | +| 展示收款方 / 分账比例 | `creators` | +| 哈希、默克尔证明、写入指令 | `royalty.basis_points_raw`、`creators_raw` | +| 检测继承模式 | `royalty.inherited`（或 `basis_points_raw === 65535`） | + +### 示例 DAS 响应（继承） + +```json +"royalty": { + "royalty_model": "creators", + "target": null, + "percent": 0.075, + "basis_points": 750, + "basis_points_raw": 65535, + "inherited": true, + "primary_sale_happened": false, + "locked": false +}, +"creators": [ + { + "address": "CJkzXwVwqiaSvMuRb3obrZHdrPFjCMBJBDrjspn72tDv", + "share": 100, + "verified": true + } +], +"creators_raw": [] +``` + +- `basis_points: 750` 是向用户展示的集合费率（7.5%）。 +- `basis_points_raw: 65535` 是叶子数据哈希中使用的链上哨兵 — **不是** 655.35% 的版税。 +- `creators` 是集合 Royalties 插件中的收款方；`creators_raw: []` 是用于哈希的叶子 creators 数组。 + +如果无法解析集合，`basis_points` 可能回退，而 `basis_points_raw` 仍为 `65535`。 + +## 检测与展示辅助函数 + +```ts +const INHERIT = 0xffff // 65535 + +function isInheritedRoyalty(royalty: { + basis_points: number + basis_points_raw?: number | null + inherited?: boolean | null +}): boolean { + return ( + royalty.inherited === true || + royalty.basis_points_raw === INHERIT + ) +} + +function leafBasisPoints(royalty: { + basis_points: number + basis_points_raw?: number | null + inherited?: boolean | null +}): number { + if (royalty.basis_points_raw != null) return royalty.basis_points_raw + if (royalty.inherited) return INHERIT + return royalty.basis_points +} + +function leafCreators(asset: { + creators: Array<{ address: string; share: number; verified: boolean }> + creators_raw?: Array<{ + address: string + share: number + verified: boolean + }> | null +}) { + return asset.creators_raw ?? asset.creators +} +``` + +使用 `@metaplex-foundation/digital-asset-standard-api`： + +```ts +import { + SELLER_FEE_BASIS_POINTS_INHERIT, + isInheritedSfbpRoyalty, + getRawSellerFeeBasisPoints, + getResolvedSellerFeeBasisPoints, +} from '@metaplex-foundation/digital-asset-standard-api' + +const royalty = asset.royalty +if (isInheritedSfbpRoyalty(royalty)) { + const rate = getResolvedSellerFeeBasisPoints(royalty) // e.g. 750 (display) + const leaf = getRawSellerFeeBasisPoints(royalty) // 65535 + const payees = asset.creators // collection payees + const leafCreators = asset.creators_raw ?? [] +} +``` + +## 不要这样做 + +- **不要**将 `65535` 或 `6.5535%` 作为面向用户的版税费率展示 — 该值位于 `basis_points_raw`。 +- **不要**假设空的 `creators_raw` 表示没有版税收款方；展示用收款方位于 `creators`。 +- 在重新计算叶子哈希或构建 Bubblegum 写入指令时，**不要**使用主字段的 `basis_points` / `creators` — 请使用 `basis_points_raw` 与 `creators_raw`。 + +## Bubblegum SDK 说明 + +`getAssetWithProof` 从 DAS 的**叶子**字段（`basis_points_raw`、`creators_raw`）构建 `metadata`，以便写入指令正确哈希。在 `getAssetWithProof` 之后如需展示费率，请读取 `rpcAsset.royalty.basis_points` 与 `rpcAsset.creators`。详见 [JavaScript SDK](/zh/smart-contracts/bubblegum-v2/sdk/javascript#getassetwithproof-and-inherited-royalties)。 + +## 相关内容 + +- [获取压缩 NFT](/zh/smart-contracts/bubblegum-v2/fetch-cnfts) +- [铸造 — 继承版税](/zh/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection) +- [更新 cNFT — 继承版税](/zh/smart-contracts/bubblegum-v2/update-cnfts#inherited-royalties) +- [哈希 NFT 数据](/zh/smart-contracts/bubblegum-v2/hashed-nft-data) +- [DAS getAsset](/zh/dev-tools/das-api/methods/get-asset) +- [FAQ — 继承版税](/zh/smart-contracts/bubblegum-v2/faq#inherited-royalties) diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/sdk/javascript.md b/src/pages/zh/smart-contracts/bubblegum-v2/sdk/javascript.md index d9886dd57..2c4c8821b 100644 --- a/src/pages/zh/smart-contracts/bubblegum-v2/sdk/javascript.md +++ b/src/pages/zh/smart-contracts/bubblegum-v2/sdk/javascript.md @@ -3,7 +3,7 @@ title: JavaScript SDK metaTitle: JavaScript SDK - Bubblegum V2 - Metaplex description: Metaplex Bubblegum V2 JavaScript SDK 完整参考文档，涵盖 Umi 设置、创建树、铸造、转移、销毁、更新、委托、冻结以及获取压缩 NFT。 created: '01-15-2025' -updated: '02-25-2026' +updated: '06-19-2026' keywords: - mpl-bubblegum JavaScript - Bubblegum V2 TypeScript SDK @@ -39,7 +39,7 @@ faqs: - q: 我可以将此 SDK 用于 Bubblegum V1 树吗？ a: 不可以。此 SDK 针对 Bubblegum V2，使用 LeafSchemaV2。V1 树请使用旧版 Bubblegum SDK。 - q: getAssetWithProof 是什么，为什么需要它？ - a: getAssetWithProof 是一个辅助函数，可以从 DAS API 一次调用中获取叶子变更指令所需的所有参数（证明、根、叶子索引、随机数、元数据）。几乎所有写入指令都需要它。 + a: getAssetWithProof 是一个辅助函数，可以从 DAS API 一次调用中获取叶子变更指令所需的所有参数（证明、根、叶子索引、随机数、元数据）。对于继承版税，metadata.sellerFeeBasisPoints 是链上叶子哨兵（65535）；已解析的集合费率位于 rpcAsset.royalty.basis_points。 --- **Bubblegum V2 JavaScript SDK**（`@metaplex-foundation/mpl-bubblegum`）是在 Solana 上创建和管理[压缩 NFT](/zh/smart-contracts/bubblegum-v2) 的推荐 TypeScript/JavaScript 库。基于 [Umi 框架](/zh/dev-tools/umi)构建，它为所有 Bubblegum V2 操作提供类型安全的函数，并自动包含 [DAS API](/zh/smart-contracts/bubblegum-v2/fetch-cnfts) 插件。 {% .lead %} @@ -197,6 +197,14 @@ await mintV2(umi, { }).sendAndConfirm(umi) ``` +### 从集合继承版税 + +当设置了 `coreCollection` 时，如果省略 `metadata.sellerFeeBasisPoints`，SDK 的 `mintV2` 辅助函数默认使用继承版税。叶子上存储 `SELLER_FEE_BASIS_POINTS_INHERIT`（`65535`）。集合必须具有 `Royalties` 插件，且 `metadata.creators` 必须为空。 + +{% code-tabs-imported from="bubblegum/mint-inherit-royalties" frameworks="umi" /%} + +有关集合设置和约束，请参阅[铸造压缩 NFT — 继承版税](/zh/smart-contracts/bubblegum-v2/mint-cnfts#inheriting-royalties-from-the-collection)。 + ### 铸造后获取资产 ID 铸造确认后，使用 `parseLeafFromMintV2Transaction` 获取叶子模式（包括资产 ID）。 @@ -276,13 +284,26 @@ const updateArgs: UpdateArgsArgs = { await updateMetadataV2(umi, { ...assetWithProof, leafOwner: assetWithProof.leafOwner, - currentMetadata: assetWithProof.metadata, + // 现有叶子元数据的指令参数名（V2 collection 为公钥）。 + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(publicKey('YourCollectionAddressHere')), + }, updateArgs, // If cNFT belongs to a collection, pass the collection address: coreCollection: publicKey('YourCollectionAddressHere'), }).sendAndConfirm(umi) ``` +`getAssetWithProof.metadata` 始终镜像叶子（继承版税时包括 `65535`）。展示时请读取 `rpcAsset.royalty.basis_points` 与 `rpcAsset.creators`。 + ## 委托压缩 NFT [叶子委托人](/zh/smart-contracts/bubblegum-v2/delegate-cnfts)可以代表所有者转移、销毁和冻结 cNFT。委托人在任何转移后重置为新所有者。 @@ -484,6 +505,21 @@ await unverifyCreatorV2(umi, { DAS API 插件由 `mplBubblegum()` 自动注册。请参阅[获取 cNFT](/zh/smart-contracts/bubblegum-v2/fetch-cnfts) 了解可用方法的完整说明。 +### getAssetWithProof and inherited royalties {% #getassetwithproof-and-inherited-royalties %} + +`getAssetWithProof` 将 `getAsset` 和 `getAssetProof` 合并为写入指令所需的参数形态。 + +| Field | Purpose | +|-------|---------| +| `metadata` | 用于哈希和写入指令的叶子规范元数据（来自 `basis_points_raw` / `creators_raw`）。继承版税时，`sellerFeeBasisPoints` 为 `65535`，`creators` 为叶子创作者列表（通常为空）。 | +| `rpcAsset` | 完整 DAS 响应。集合解析后的展示值位于 `royalty.basis_points`、`royalty.percent` 与 `creators`；叶子值位于 `royalty.basis_points_raw` 与 `creators_raw`。 | + +`updateMetadataV2` 仍将其现有叶子参数命名为 `currentMetadata`（IDL）。请从 `assetWithProof.metadata` 的叶子字段构建该 `MetadataArgsV2`，并将 V2 `collection` 设为公钥。 + +直接读取 DAS 的客户端应遵循[读取继承版税](/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties)。 + +{% code-tabs-imported from="bubblegum/get-asset-with-proof-inherited" frameworks="umi" /%} + ### 获取单个 cNFT ```ts {% title="fetch-asset.ts" %} @@ -606,7 +642,8 @@ const tx = await mintV2(umi, { ... }).buildAndSign(umi) | `setNonTransferableV2` | 使 cNFT 永久灵魂绑定（不可逆） | | `verifyCreatorV2` | 在创建者条目上设置 verified 标志 | | `unverifyCreatorV2` | 从创建者条目中移除 verified 标志 | -| `getAssetWithProof` | 获取写入指令所需的所有证明参数 | +| `getAssetWithProof` | 获取证明参数；`metadata` 为叶子规范值，展示用继承值位于 `rpcAsset` | +| `SELLER_FEE_BASIS_POINTS_INHERIT` | 从 MPL-Core 集合继承版税的哨兵常量（`65535`） | | `findLeafAssetIdPda` | 从树地址和叶子索引推导 cNFT 资产 ID | | `parseLeafFromMintV2Transaction` | 从铸造交易中提取叶子模式（包括资产 ID） | diff --git a/src/pages/zh/smart-contracts/bubblegum-v2/update-cnfts.md b/src/pages/zh/smart-contracts/bubblegum-v2/update-cnfts.md index 0f759481c..ddd2044eb 100644 --- a/src/pages/zh/smart-contracts/bubblegum-v2/update-cnfts.md +++ b/src/pages/zh/smart-contracts/bubblegum-v2/update-cnfts.md @@ -3,7 +3,7 @@ title: 更新压缩NFT metaTitle: 更新压缩NFT - Bubblegum V2 description: 了解如何在Bubblegum上更新压缩NFT。 created: '01-15-2025' -updated: '02-24-2026' +updated: '06-19-2026' keywords: - update compressed NFT - update cNFT @@ -24,6 +24,8 @@ faqs: a: 您可以更新UpdateArgsArgs中定义的名称、URI、卖家费用基准点及其他元数据字段。对于要更改的字段使用some('newValue')。 - q: 更新时需要传递集合吗？ a: 是的，如果cNFT属于集合。请传递带有集合公钥的coreCollection参数。集合权限必须签署交易。 + - q: 如何更新从集合继承版税的cNFT？ + a: 将getAssetWithProof的叶子元数据作为updateMetadataV2的currentMetadata参数传入（IDL中表示现有叶子状态的名称）。继承版税时sellerFeeBasisPoints为链上哨兵。 --- ## Summary @@ -34,6 +36,7 @@ faqs: - Collection authority updates cNFTs that belong to a collection - Tree authority updates cNFTs that do not belong to a collection - Changes are reflected in the merkle tree and indexed by DAS API providers +- 将 `getAssetWithProof` 的叶子元数据作为 `updateMetadataV2` 的 `currentMetadata` 参数传入（IDL 中表示现有叶子状态的名称） **updateMetadataV2**指令可用于修改压缩NFT的元数据。默克尔根会更新以反映数据的传播哈希，符合[Metaplex DAS API](https://github.com/metaplex-foundation/digital-asset-standard-api)的RPC提供商将更新其cNFT索引。 @@ -90,7 +93,17 @@ const updateArgs: UpdateArgsArgs = { await updateMetadataV2(umi, { ...assetWithProof, leafOwner, - currentMetadata: assetWithProof.metadata, + currentMetadata: { + name: assetWithProof.metadata.name, + symbol: assetWithProof.metadata.symbol, + uri: assetWithProof.metadata.uri, + sellerFeeBasisPoints: assetWithProof.metadata.sellerFeeBasisPoints, + primarySaleHappened: assetWithProof.metadata.primarySaleHappened, + isMutable: assetWithProof.metadata.isMutable, + tokenStandard: assetWithProof.metadata.tokenStandard, + creators: assetWithProof.metadata.creators, + collection: some(publicKey('22222222222222222222222222222222')), + }, updateArgs, // 可选参数。如果您的权限是与当前umi身份不同的签名者类型， // 在此处分配该签名者。 @@ -100,6 +113,22 @@ await updateMetadataV2(umi, { }).sendAndConfirm(umi) ``` +{% callout type="note" title="写入指令使用叶子元数据" %} +`getAssetWithProof.metadata` 始终是叶子规范值 — 继承版税时包括 `sellerFeeBasisPoints: 65535`。集合解析后的展示值位于 `rpcAsset.royalty.basis_points` 与 `rpcAsset.creators`。 + +`updateMetadataV2` 的 `currentMetadata` 参数是现有叶子元数据的 IDL 名称（V2 形态：`collection` 为公钥）。请从 `assetWithProof.metadata` 构建它。 + +读取资产时关于 DAS 响应字段的说明，请参阅[读取继承版税](/zh/smart-contracts/bubblegum-v2/reading-inherited-royalties)。 +{% /callout %} + +## 继承版税 {% #inherited-royalties %} + +通过将 `updateArgs.sellerFeeBasisPoints` 设为 `some(SELLER_FEE_BASIS_POINTS_INHERIT)`，可将 cNFT **切换为**继承版税。集合必须具有 `Royalties` 插件，且更新后的元数据 `creators` 数组必须为空。 + +要从继承版税**切换回**明确百分比 — 例如在[从集合中移除 cNFT](/zh/smart-contracts/bubblegum-v2/collections#inherited-royalties)之前 — 请传入所需的 basis points： + +{% code-tabs-imported from="bubblegum/update-inherit-royalties" frameworks="umi" /%} + {% /totem %} {% /dialect %} {% /dialect-switcher %} @@ -107,12 +136,27 @@ await updateMetadataV2(umi, { ## Notes - The update authority depends on whether the cNFT belongs to a collection. Collection cNFTs use the collection authority; standalone cNFTs use the tree authority. -- You must pass `currentMetadata` from `getAssetWithProof` so the program can verify the current leaf before applying updates. +- 将 `getAssetWithProof` 的叶子元数据作为 `updateMetadataV2` 的 `currentMetadata` 参数传入，以便程序在应用更新前验证当前叶子。 - Use `some()` for fields you want to update and omit fields you want to keep unchanged. +- Inherited seller fees require an empty leaf-level `creators` array and a collection with the `Royalties` plugin. ## FAQ -# +### 谁可以更新压缩 NFT 的元数据？ + +如果 cNFT 属于集合，只有集合权限可以更新。如果不属于集合，树权限（树创建者或委托人）可以更新。 + +### 可以在 cNFT 上更新哪些字段？ + +你可以更新 `UpdateArgsArgs` 中定义的名称、URI、seller fee basis points 及其他元数据字段。对要更改的字段使用 `some('newValue')`。 + +### 更新时需要传递集合吗？ + +是的，如果 cNFT 属于集合。请传递带有集合公钥的 `coreCollection` 参数。集合权限必须签署交易。 + +### 如何更新从集合继承版税的 cNFT？ + +将 `getAssetWithProof` 的叶子元数据作为 `updateMetadataV2` 的 `currentMetadata` 参数传入，以便使用链上哨兵进行验证。使用 `updateArgs.sellerFeeBasisPoints` 的 `some(SELLER_FEE_BASIS_POINTS_INHERIT)` 切换为继承版税，或使用明确数字切换离开继承版税。 ## Glossary @@ -122,4 +166,5 @@ await updateMetadataV2(umi, { | **Collection Authority** | The update authority of the MPL-Core collection, authorized to update cNFTs in that collection | | **Tree Authority** | The tree creator or delegate, authorized to update cNFTs that do not belong to a collection | | **UpdateArgsArgs** | The TypeScript type defining which metadata fields to update, using Option wrappers | -| **currentMetadata** | The existing metadata of the cNFT, fetched via getAssetWithProof and required for verification | +| **currentMetadata** | `updateMetadataV2` 上表示现有叶子元数据的 IDL 参数；请从 `getAssetWithProof.metadata` 构建 | +| **SELLER_FEE_BASIS_POINTS_INHERIT** | Sentinel value `65535` indicating royalties are inherited from the MPL-Core collection |