nft-blockchain

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NFT and Blockchain in Decentraland

Decentraland 中的 NFT 与区块链

Display NFT Artwork

展示 NFT 艺术作品

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.

使用

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
```
的合约也能够解析。

Available Frame Styles

可用画框样式

typescript

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

typescript

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

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.

使用

@dcl/sdk/src/players

中的

getPlayer()

，通过

player.userId

获取玩家的 Ethereum 地址。在执行任何区块链交互之前，始终检查

isGuest

——访客玩家没有连接钱包。

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 }
```
.

使用

~system/SignedFetch

中的

signedFetch

向后端发送经过身份验证的请求。它会自动注入签名身份标头（ADR-44），由你的后端进行验证——无需自行构建或传递这些标头。

签名：

signedFetch({ url, init: { method?, headers?, body? } })

。

响应为

{ ok, status, statusText, headers, body }

；body
是字符串——请调用

JSON.parse(response.body)

（没有

.json()

）。

它不需要事先与玩家交互（与受限操作不同）。
某个库会自行执行请求，但只需要签名标头时？使用同一模块中的
```
getHeaders({ url, init? })
```
——它返回
```
{ 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.

bash

npm install eth-connect

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).

对于直接的智能合约调用，使用

eth-connect

，并结合

@dcl/sdk/ethereum-provider

中的

createEthereumProvider

。将 ABI 存储在单独的文件中，通过

ContractFactory

创建合约实例，然后调用读取（无需 gas）或写入（需要 gas，会提示用户签名）函数。

bash

npm install eth-connect

读取操作（view/pure 函数）不需要 gas。写入操作会提示玩家签名并需要 gas。

将所有异步区块链调用包装在

executeTask(async () => { ... })

中。妥善处理错误——区块链操作可能会失败（用户拒绝、gas 不足、网络问题）。

Gas Price and Balance

Gas 价格与余额

Use

requestManager.eth_gasPrice()

and

requestManager.eth_getBalance()

from

eth-connect

to check current gas prices and account ETH balances.

使用

eth-connect

中的

requestManager.eth_gasPrice()

和

requestManager.eth_getBalance()

查询当前 gas 价格和账户 ETH 余额。

Custom RPC Calls

自定义 RPC 调用

Use

sendAsync

from

~system/EthereumController

for low-level Ethereum RPC calls not covered by eth-connect helpers.

使用

~system/EthereumController

中的

sendAsync

执行

eth-connect

辅助函数未涵盖的低级 Ethereum RPC 调用。

Opening External URLs / NFT Dialogs

打开外部 URL / NFT 弹窗

Use

openExternalUrl

and

openNftDialog

from

~system/RestrictedActions

to open external links and NFT detail views.

使用

~system/RestrictedActions

中的

openExternalUrl

和

openNftDialog

打开外部链接和 NFT 详情视图。

Testing with Sepolia

使用 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.

开发时，使用 Sepolia 测试网：将 MetaMask 设置为 Sepolia，从水龙头（faucet）获取测试 ETH，并将合约部署到 Sepolia。合约地址在主网和测试网之间有所不同。

dcl-crypto-toolkit (Higher-Level API)

dcl-crypto-toolkit（高级 API）

For common blockchain operations, use

dcl-crypto-toolkit

instead of raw

eth-connect

. It provides a cleaner API for the most frequent tasks.

bash

npm install dcl-crypto-toolkit

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()
```
)

对于常见的区块链操作，使用

dcl-crypto-toolkit

而不是原始的

eth-connect

。它为最常用的任务提供了更简洁的 API。

bash

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 代币： 发送、检查余额、检查/设置 allowance（
```
crypto.currency.*
```
）
ERC721/NFT： 检查持有的代币（token gating）、转移、approval 管理（
```
crypto.nft.*
```
）
Marketplace： 买入（
```
executeOrder
```
）、卖出（
```
createOrder
```
）、取消（
```
cancelOrder
```
）、检查授权（
```
crypto.marketplace.*
```
）
签名消息： 使用玩家钱包签署 EIP-712 类型化数据（
```
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.

按 NFT 所有权： 使用

crypto.nft.checkTokens(contractAddress, tokenIds?)

——返回玩家是否持有该合约的代币。省略

tokenIds

可检查该合约的任意代币。根据结果授予或拒绝访问权限。

按 MANA 余额： 使用

crypto.mana.myBalance()

检查余额（或使用

crypto.currency.balance(contractAddress, address)

检查其他 ERC20 代币），并根据持仓量对访问权限进行门控。

Quick Decision Guide

快速决策指南

Task	Use
Send MANA	`crypto.mana.send()`
Check own MANA balance	`crypto.mana.myBalance()`
Check any address's MANA balance	`crypto.mana.balance(address)`
Send any ERC20 token	`crypto.currency.send()`
Check ERC20 balance	`crypto.currency.balance(contract, address)`
Transfer an NFT	`crypto.nft.transfer()`
Check NFT ownership / token gating	`crypto.nft.checkTokens()`
Buy from marketplace	`crypto.marketplace.executeOrder()`
List NFT for sale	`crypto.marketplace.createOrder()`
Sign a message	`crypto.ethereum.signMessageAdvanced()`
Custom smart contract	`eth-connect` (see above)
Authenticated API call	`signedFetch` (see above)

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

任务	使用
发送 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()`
从 Marketplace 购买	`crypto.marketplace.executeOrder()`
挂牌出售 NFT	`crypto.marketplace.createOrder()`
签名消息	`crypto.ethereum.signMessageAdvanced()`
自定义智能合约	`eth-connect` （见上文）
经过身份验证的 API 调用	`signedFetch` （见上文）

有关完整代码示例和实现模式（包括 dcl-crypto-toolkit 库 API），请参阅 '{baseDir}/references/blockchain-patterns.md'。