nft-blockchain

NFT and Blockchain in Decentraland

Display NFT Artwork

Use NftShape to show an NFT in a decorative picture frame. Provide the NFT URN and choose a frame style. The image is loaded automatically from the NFT's metadata (fetched through Decentraland's OpenSea proxy, opensea.decentraland.org) — any NFT that OpenSea supports can be displayed, across multiple chains.

NFT URN format: urn:decentraland:<chain>:<contractStandard>:<contractAddress>:<tokenId>

• Example: urn:decentraland:ethereum:erc721:0x06012c8cf97bead5deae237070f9587f8e7a266d:558536
• <chain> supported values (forwarded verbatim to the OpenSea v2 API; unrecognized chains are rejected): ethereum, matic, klaytn, bsc, arbitrum, arbitrum_nova, avalanche, optimism, solana, base, blast, zora.
• <contractStandard> is typically erc721. The image is served from the OpenSea response, so contracts OpenSea indexes as erc1155 also resolve.

Available Frame Styles

NftFrameType.NFT_CLASSIC            // Simple classic frame
NftFrameType.NFT_BAROQUE_ORNAMENT

Check Player Wallet

Use getPlayer() from @dcl/sdk/src/players to get the player's Ethereum address via player.userId. Always check isGuest before any blockchain interaction -- guest players don't have a connected wallet.

Signed Requests

Use signedFetch from ~system/SignedFetch to send authenticated requests to a backend. It automatically injects signed identity headers (ADR-44) that your backend verifies — you do not build or pass them yourself.

• Signature: signedFetch({ url, init: { method?, headers?, body? } }).
• Response is { ok, status, statusText, headers, body }; body is a string — call JSON.parse(response.body) (there is no .json()).
• It does not require prior player interaction (unlike restricted actions).
• Need only the signed headers for a library that does its own fetching? Use getHeaders({ url, init? }) from the same module — it returns { headers }.

Smart Contract Interaction

For direct smart contract calls, use eth-connect with createEthereumProvider from @dcl/sdk/ethereum-provider. Store ABIs in separate files, create a contract instance via ContractFactory, then call read (no gas) or write (requires gas, prompts user to sign) functions.

Read operations (view/pure functions) don't require gas. Write operations prompt the player to sign and require gas.

Wrap all async blockchain calls in executeTask(async () => { ... }). Handle errors gracefully — blockchain operations can fail (rejected by user, insufficient gas, network issues).

Gas Price and Balance

Use requestManager.eth_gasPrice() and requestManager.eth_getBalance() from eth-connect to check current gas prices and account ETH balances.

Custom RPC Calls

Use sendAsync from ~system/EthereumController for low-level Ethereum RPC calls not covered by eth-connect helpers.

Opening External URLs / NFT Dialogs

Use openExternalUrl and openNftDialog from ~system/RestrictedActions to open external links and NFT detail views.

Testing with Sepolia

For development, use the Sepolia testnet: set MetaMask to Sepolia, get test ETH from a faucet, deploy contracts to Sepolia. Contract addresses differ between mainnet and testnet.

dcl-crypto-toolkit (Higher-Level API)

For common blockchain operations, use dcl-crypto-toolkit instead of raw eth-connect. It provides a cleaner API for the most frequent tasks.

Import: import * as crypto from 'dcl-crypto-toolkit'. Modules: ethereum, mana, currency, nft, marketplace, services, wearable, contract. There is NO top-level crypto.signMessage.

Capabilities:

• MANA operations: send, check balance (crypto.mana.send / .myBalance / .balance)
• ERC20 tokens: send, check balance, check/set allowance (crypto.currency.*)
• ERC721/NFT: check tokens held (token gating), transfer, approval management (crypto.nft.*)
• Marketplace: buy (executeOrder), sell (createOrder), cancel (cancelOrder), check authorization (crypto.marketplace.*)
• Sign message: sign EIP-712 typed data with player wallet (crypto.ethereum.signMessageAdvanced())

Token Gating

By NFT ownership: Use crypto.nft.checkTokens(contractAddress, tokenIds?) — returns whether the player holds tokens of that contract. Omit tokenIds to check any token of the contract. Grant or deny access on the result.

By MANA balance: Check crypto.mana.myBalance() (or crypto.currency.balance(contractAddress, address) for other ERC20 tokens) to gate access based on holdings.

Quick Decision Guide

Example scenes

Engine-team test scenes exercising these APIs against the real runtime:

• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/5,90-scene-bounds-check — NftShape.create() with a live urn:decentraland:ethereum:erc721:<contract>:<tokenId> URN, mounted on a moving platform that carries it across the parcel boundary (so it also shows an NFT frame being culled out of bounds).
• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/80,-4-restricted-actions — openNftDialog({ urn }) and openExternalUrl driven from React-ECS buttons, alongside every other RestrictedAction. Note the scene declares neither OPEN_EXTERNAL_LINK nor an NFT permission in requiredPermissions and both still run.
• https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/66,6-signed-fetch — signedFetch on click; reads response.ok/.status/.body and inspects the auto-added signature headers, with an empty requiredPermissions.

For full code examples and implementation patterns, including the dcl-crypto-toolkit library API, see '{baseDir}/references/blockchain-patterns.md'.