nft-blockchain

Decentraland の NFT とブロックチェーン

NFT アートワークを表示する

NftShape を使うと、装飾的な額縁に NFT を表示できます。NFT の URN を指定し、額縁のスタイルを選択します。画像は NFT のメタデータから自動的に読み込まれます（Decentraland の OpenSea プロキシ opensea.decentraland.org 経由で取得します）。複数のチェーンにわたって、OpenSea がサポートするあらゆる NFT を表示できます。

NFT URN の形式： urn:decentraland:<chain>:<contractStandard>:<contractAddress>:<tokenId>

• 例：urn:decentraland:ethereum:erc721:0x06012c8cf97bead5deae237070f9587f8e7a266d:558536
• <chain> でサポートされる値（OpenSea v2 API にそのまま渡されます。認識されないチェーンは拒否されます）：ethereum、matic、klaytn、bsc、arbitrum、arbitrum_nova、avalanche、optimism、solana、base、blast、zora。
• <contractStandard> は通常 erc721 です。画像は OpenSea のレスポンスから提供されるため、OpenSea が erc1155 としてインデックス化したコントラクトも解決されます。

利用可能な額縁スタイル

NftFrameType.NFT_CLASSIC            // Simple classic frame
NftFrameType.NFT_BAROQUE_ORNAMENT   // Ornate baroque
NftFrameType.NFT_DIAMOND_ORNAMENT   // Diamond pattern
NftFrameType.NFT_MINIMAL_WIDE       // Minimal wide border
NftFrameType.NFT_MINIMAL_GREY       // Minimal grey border
NftFrameType.NFT_BLOCKY             // Pixelated/blocky
NftFrameType.NFT_GOLD_EDGES         // Gold edge trim
NftFrameType.NFT_GOLD_CARVED        // Carved gold
NftFrameType.NFT_GOLD_WIDE          // Wide gold border
NftFrameType.NFT_GOLD_ROUNDED       // Rounded gold
NftFrameType.NFT_METAL_MEDIUM       // Medium metal
NftFrameType.NFT_METAL_WIDE         // Wide metal
NftFrameType.NFT_METAL_SLIM         // Slim metal
NftFrameType.NFT_METAL_ROUNDED      // Rounded metal
NftFrameType.NFT_PINS               // Pinned to wall
NftFrameType.NFT_MINIMAL_BLACK      // Minimal black
NftFrameType.NFT_MINIMAL_WHITE      // Minimal white
NftFrameType.NFT_TAPE               // Taped to wall
NftFrameType.NFT_WOOD_SLIM          // Slim wood
NftFrameType.NFT_WOOD_WIDE          // Wide wood
NftFrameType.NFT_WOOD_TWIGS         // Twig/branch wood
NftFrameType.NFT_CANVAS             // Canvas style
NftFrameType.NFT_NONE               // No frame

プレイヤーのウォレットを確認する

@dcl/sdk/src/players の getPlayer() を使い、player.userId 経由でプレイヤーの Ethereum アドレスを取得します。ブロックチェーンとのやり取りを行う前に、必ず isGuest を確認してください。ゲストプレイヤーはウォレットに接続されていません。

署名付きリクエスト

バックエンドに認証済みリクエストを送信するには、~system/SignedFetch の signedFetch を使います。署名付き ID ヘッダー（ADR-44）が自動的に追加され、バックエンドで検証されます。自分でヘッダーを作成したり渡したりする必要はありません。

• シグネチャ：signedFetch({ url, init: { method?, headers?, body? } })。
• レスポンスは { ok, status, statusText, headers, body } です。body は文字列です。JSON.parse(response.body) を呼び出してください（.json() はありません）。
• 事前にプレイヤーの操作を必要としません（制限付きアクションとは異なります）。
• ライブラリが独自にデータを取得する場合など、署名付きヘッダーだけが必要な場合は、同じモジュールの getHeaders({ url, init? }) を使います。{ headers } が返されます。

スマートコントラクトとのやり取り

スマートコントラクトを直接呼び出す場合は、eth-connect と @dcl/sdk/ethereum-provider の createEthereumProvider を使います。ABI は別ファイルに保存し、ContractFactory を介してコントラクトインスタンスを作成してから、読み取り（ガス不要）または書き込み（ガスが必要で、ユーザーに署名を求めます）関数を呼び出します。

npm install eth-connect

読み取り操作（view／pure 関数）ではガスは不要です。書き込み操作ではプレイヤーに署名を求め、ガスが必要です。

すべての非同期ブロックチェーン呼び出しを executeTask(async () => { ... }) でラップします。エラーは適切に処理してください。ブロックチェーン操作は、ユーザーによる拒否、ガス不足、ネットワークの問題などにより失敗することがあります。

ガス価格と残高

現在のガス価格とアカウントの ETH 残高を確認するには、eth-connect の requestManager.eth_gasPrice() と requestManager.eth_getBalance() を使います。

カスタム RPC 呼び出し

eth-connect のヘルパーでは対応していない低レベルの Ethereum RPC 呼び出しには、~system/EthereumController の sendAsync を使います。

外部 URL／NFT ダイアログを開く

外部リンクや NFT の詳細ビューを開くには、~system/RestrictedActions の openExternalUrl と openNftDialog を使います。

Sepolia でのテスト

開発では Sepolia テストネットを使います。MetaMask を Sepolia に設定し、フォーセットからテスト用 ETH を取得して、コントラクトを Sepolia にデプロイします。コントラクトのアドレスは、メインネットとテストネットで異なります。

dcl-crypto-toolkit（高レベル API）

一般的なブロックチェーン操作には、生の eth-connect ではなく dcl-crypto-toolkit を使用してください。よく使われるタスク向けに、よりシンプルな API を提供します。

npm install dcl-crypto-toolkit

インポート：import * as crypto from 'dcl-crypto-toolkit'。モジュール：ethereum、mana、currency、nft、marketplace、services、wearable、contract。トップレベルの crypto.signMessage はありません。

機能：

• MANA 操作： 送金、残高確認（crypto.mana.send / .myBalance / .balance）
• ERC20 トークン： 送金、残高確認、使用許可の確認／設定（crypto.currency.*）
• ERC721／NFT： 保有トークンの確認（トークンゲーティング）、移転、承認管理（crypto.nft.*）
• マーケットプレイス： 購入（executeOrder）、販売（createOrder）、キャンセル（cancelOrder）、認可の確認（crypto.marketplace.*）
• メッセージへの署名： プレイヤーのウォレットで EIP-712 の型付きデータに署名（crypto.ethereum.signMessageAdvanced()）

トークンゲーティング

NFT の所有状況による判定： crypto.nft.checkTokens(contractAddress, tokenIds?) を使用します。プレイヤーがそのコントラクトのトークンを保有しているかどうかを返します。tokenIds を省略すると、そのコントラクトの任意のトークンを確認します。結果に基づいてアクセスを許可または拒否します。

MANA 残高による判定： crypto.mana.myBalance() を確認します（その他の ERC20 トークンの場合は crypto.currency.balance(contractAddress, address)）。保有状況に基づいてアクセスを制御できます。

すぐに使える選択ガイド

タスク	使用するもの
MANA を送金する	crypto.mana.send()
自分の MANA 残高を確認する	crypto.mana.myBalance()
任意のアドレスの MANA 残高を確認する	crypto.mana.balance(address)
任意の ERC20 トークンを送金する	crypto.currency.send()
ERC20 残高を確認する	crypto.currency.balance(contract, address)
NFT を移転する	crypto.nft.transfer()
NFT の所有状況／トークンゲーティングを確認する	crypto.nft.checkTokens()
マーケットプレイスで購入する	crypto.marketplace.executeOrder()
NFT を出品する	crypto.marketplace.createOrder()
メッセージに署名する	crypto.ethereum.signMessageAdvanced()
カスタムスマートコントラクト	eth-connect（上記を参照）
認証付き API 呼び出し	signedFetch（上記を参照）

シーンの例

実際のランタイムでこれらの API を実行する、エンジンチームのテストシーン：

• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/5,90-scene-bounds-check — ライブの urn:decentraland:ethereum:erc721:<contract>:<tokenId> URN を指定した NftShape.create()。移動するプラットフォームに取り付けられ、区画の境界を越えて運ばれます（NFT フレームが境界外でカリングされる様子も確認できます）。
• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/80,-4-restricted-actions — React-ECS ボタンから実行する openNftDialog({ urn }) と openExternalUrl を、ほかのすべての RestrictedAction と並べて確認できます。このシーンでは requiredPermissions に OPEN_EXTERNAL_LINK も NFT 権限も宣言していませんが、どちらも実行されます。
• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/66,6-signed-fetch — クリック時の signedFetch。response.ok／.status／.body を読み取り、自動追加される署名ヘッダーを確認します。requiredPermissions は空です。

dcl-crypto-toolkit ライブラリ API を含む、完全なコード例と実装パターンについては、「{baseDir}/references/blockchain-patterns.md」を参照してください。