ERC1155

这个模块提供了与 ERC1155 合约相关的接口、预设和实用程序。

有关 ERC1155 的概述,请阅读我们的 ERC1155 指南

核心

IERC1155

use openzeppelin_token::erc1155::interface::IERC1155;

IERC1155 标准的接口,如 EIP1155 中所定义。

0x6114a8f75559e1b39fcba08ce02961a1aa082d9256a158dd3e64964e4b1b52

函数

balance_of(account: ContractAddress, token_id: u256) → u256 external

返回 account 拥有的 token_id tokens 的数量。

balance_of_batch(accounts: Span<ContractAddress>, token_ids: Span<u256>) → Span<u256> external

返回从 accountstoken_ids 对派生的余额列表。

safe_transfer_from(from: ContractAddress, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>) external

如果 toIERC1155Receiver 或一个 account,则将 token_idvalue 数量的所有权从 from 转移到 to

data 是附加数据,它没有指定的格式,并传递给 to

发出一个 TransferSingle 事件。

safe_batch_transfer_from(from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>) external

如果 toIERC1155Receiver 或一个 account,则将 token_idsvalues 对的所有权从 from 转移到 to

data 是附加数据,它没有指定的格式,并传递给 to

发出一个 TransferBatch 事件。

set_approval_for_all(operator: ContractAddress, approved: bool) external

启用或禁用 operator 管理所有调用者的资产的权限。

发出一个 ApprovalForAll 事件。

is_approved_for_all(owner: ContractAddress, operator: ContractAddress) -> bool external

查询 operator 是否为 owner 的授权 operator 。

事件

TransferSingle(operator: ContractAddress, from: ContractAddress, to: ContractAddress, id: u256, value: u256) event

value 数量的 id token 通过 operatorfrom 转移到 to 时发出。

TransferBatch(operator: ContractAddress, from: ContractAddress, to: ContractAddress, ids: Span<u256>, values: Span<u256>) event

当通过 operatorfrom 转移到 to 的一批 values 数量的 ids tokens 时发出。

ApprovalForAll(owner: ContractAddress, operator: ContractAddress, approved: bool) event

owner 启用或禁用 operator 管理所有 owner 的资产时发出。

URI(value: ByteArray, id: u256) event

id token 的 token URI 更新为 value 时发出。

IERC1155MetadataURI

use openzeppelin_token::erc1155::interface::IERC1155MetadataURI;

EIP1155 中可选元数据函数的接口。

0xcabe2400d5fe509e1735ba9bad205ba5f3ca6e062da406f72f113feb889ef7

函数

函数

uri(token_id: u256) -> ByteArray external

返回 token_id token 的 Uniform Resource Identifier (URI)。

ERC1155Component

use openzeppelin_token::erc1155::ERC1155Component;

实现 IERC1155IERC1155MetadataURI 的 ERC1155 组件。

实施 SRC5Component 是本组件需要实现的要求。
参阅 Hooks 以了解如何使用 hooks。

Hooks

Hooks 是函数,其实例可以扩展组件源代码的功能。每个使用 ERC1155Component 的合约都应提供 ERC1155HooksTrait 的实现。对于基本 token 合约,必须提供没有逻辑的空实现。

你可以使用 openzeppelin_token::erc1155::ERC1155HooksEmptyImpl,它已经作为库的一部分提供,用于此目的。

before_update(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>) hook

在任何其他逻辑之前,在 update 函数的开头执行的函数。

after_update(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>) hook

update 函数的末尾执行的函数。

可嵌入的函数

balance_of(self: @ContractState, account: ContractAddress, token_id: u256) → u256 external

返回 account 拥有的 token_id tokens 的数量。

balance_of_batch(self: @ContractState, accounts: Span<ContractAddress>, token_ids: Span<u256>) → Span<u256> external

返回从 accountstoken_ids 对派生的余额列表。

要求:

  • token_idsaccounts 必须具有相同的长度。

safe_transfer_from(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>) external

如果 to 是一个 account 或 IERC1155Receiver,则将 token_idvalue 数量的所有权从 from 转移到 to

data 是附加数据,它没有指定的格式,并传递给 to

当将 tokens 转移到不受信任的合约时,此函数可能会允许重入攻击,当在接收者上调用 on_ERC1155_received 时。确保遵循检查-效果-交互模式,并在与不受信任的合约交互时考虑使用重入保护。

要求:

  • 调用者要么被批准,要么是 token_id 的 owner。

  • from 不是零地址。

  • to 不是零地址。

  • 如果 to 引用一个非 account 合约,它必须实现 IERC1155Receiver::on_ERC1155_received 并返回所需的 magic value。

发出一个 TransferSingle 事件。

safe_batch_transfer_from(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>) external

如果 to 是一个 account 或 IERC1155Receiver,则将 valuestoken_ids 对的所有权从 from 转移到 to

data 是附加数据,它没有指定的格式,并传递给 to

当将 tokens 转移到不受信任的合约时,此函数可能会允许重入攻击,当在接收者上调用 on_ERC1155_batch_received 时。确保遵循检查-效果-交互模式,并在与不受信任的合约交互时考虑使用重入保护。

要求:

  • 调用者要么被批准,要么是 token_id 的 owner。

  • from 不是零地址。

  • to 不是零地址。

  • token_idsvalues 必须具有相同的长度。

  • 如果 to 引用一个非 account 合约,它必须实现 IERC1155Receiver::on_ERC1155_batch_received 并返回接受 magic value。

如果数组包含一个元素,则发出一个 TransferSingle 事件, 否则发出 TransferBatch 事件。

set_approval_for_all(ref self: ContractState, operator: ContractAddress, approved: bool) external

启用或禁用 operator 管理所有调用者资产的权限。

要求:

  • operator 不能是调用者。

发出一个 ApprovalForAll 事件。

is_approved_for_all(self: @ContractState, owner: ContractAddress, operator: ContractAddress) -> bool external

查询 operator 是否为 owner 的授权 operator 。

uri(self: @ContractState, token_id: u256) -> ByteArray external

此实现为*所有* token 类型返回相同的 URI。它依赖于 token 类型 ID 替换机制 在 EIP 中指定

调用此函数的客户端必须将 {id} 子字符串替换为 实际的 token 类型 ID。

balanceOf(self: @ContractState, account: ContractAddress, tokenId: u256) → u256 external

balanceOfBatch(self: @ContractState, accounts: Span<ContractAddress>, tokenIds: Span<u256>) → Span<u256> external

safeTransferFrom(ref self: ContractState, from: ContractAddress, to: ContractAddress, tokenId: u256, value: u256, data: Span<felt252>) external

safeBatchTransferFrom(ref self: ContractState, from: ContractAddress, to: ContractAddress, tokenIds: Span<u256>, values: Span<u256>, data: Span<felt252>) external

setApprovalForAll(ref self: ContractState, operator: ContractAddress, approved: bool) external

isApprovedForAll(self: @ContractState, owner: ContractAddress, operator: ContractAddress) -> bool external

内部函数

initializer(ref self: ContractState, base_uri: ByteArray) internal

通过将 token 的基本 URI 设置为 base_uri 并注册支持的接口来初始化合约。这应该只在合约的 constructor 中使用。

大多数 ERC1155 合约都公开了 IERC1155MetadataURI 接口,这是此初始化器旨在支持的。如果合约没有公开 IERC1155MetadataURI 接口,这意味着 tokens 没有 URI,则合约必须改为在 constructor 中使用 initializer_no_metadata。不遵守这些指示可能会导致意想不到的问题,尤其是在 UI 中。

initializer_no_metadata(ref self: ContractState) internal

通过仅注册 IERC1155 接口来初始化没有元数据的合约。

此初始化器应仅在合约不公开 IERC1155MetadataURI 接口的特定实例中才在构造期间使用。使用此初始化器初始化合约意味着 tokens 将没有 URI。

mint_with_acceptance_check(ref self: ContractState, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>) internal

创建 value 数量的 token_id 类型的 tokens,并将它们分配给 to

要求:

  • to 不能是零地址。

  • 如果 to 引用智能合约,它必须实现 IERC1155Receiver::on_ERC1155_received 并且返回接受 magic value。

发出一个 TransferSingle 事件。

batch_mint_with_acceptance_check(ref self: ContractState, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>) internal

mint_with_acceptance_check 的批量版本。

要求:

  • to 不能是零地址。

  • token_idsvalues 必须具有相同的长度。

  • 如果 to 引用智能合约,它必须实现 IERC1155Receiver::on_ERC1155_batch_received 并且返回接受 magic value。

发出一个 TransferBatch 事件。

burn(ref self: ContractState, from: ContractAddress, token_id: u256, value: u256) internal

from 销毁 token_id 类型的 value 数量的 tokens。

要求:

  • from 不能是零地址。

  • from 必须至少有 token_id 类型的 value 数量的 tokens。

发出一个 TransferSingle 事件。

batch_burn(ref self: ContractState, from: ContractAddress, token_ids: Span<u256>, values: Span<u256>) internal

burn 的批量版本。

要求:

  • from 不能是零地址。

  • from 必须至少有 token_id 类型的 value 数量的 tokens。

  • token_idsvalues 必须具有相同的长度。

发出一个 TransferBatch 事件。

update_with_acceptance_check(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>) internal

update 的版本,它通过调用 onERC1155ReceivedonERC1155BatchReceived 在接收者中执行 token 接受检查,如果 它实现了 IERC1155Receiver,否则通过检查它是否为一个 account。

要求:

  • to 要么是一个 account 合约,要么支持 IERC1155Receiver 接口。

  • token_idsvalues 必须具有相同的长度。

如果数组包含一个元素,则发出一个 TransferSingle 事件, 否则发出 TransferBatch 事件。

update(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>) internal

id 类型的 value 数量的 tokens 从 from 转移到 to。 如果 from(或 to)是零地址,将 mint(或 burn)。

要求:

  • token_idsvalues 必须具有相同的长度。

如果数组包含一个元素,则发出一个 TransferSingle 事件, 否则发出 TransferBatch 事件。

可以使用 ERC1155HooksTrait 扩展此函数,以在转账、mint 或 burn 之前和/或之后添加功能。
此函数中未执行 ERC1155 接受检查。 请参阅 update_with_acceptance_check

_set_base_uri(ref self: ContractState, base_uri: ByteArray) internal

通过依赖于 token 类型 ID 在 EIP 中指定的替换机制,为所有 token 类型设置一个新的 URI。

通过这种机制,URI 或上述 URI 处 JSON 文件中任何值中出现的任何 {id} 子字符串都将被客户端替换为 token 类型 ID。

例如,https://token-cdn-domain/\{id\}.json URI 将被 客户端解释为 https://token-cdn-domain/000000000000...000000000000004cce0.json 对于 token 类型 ID 0x4cce0

因为这些 URI 无法通过 URI 事件有意义地表示, 此函数不发出任何事件。

事件

TransferSingle(operator: ContractAddress, from: ContractAddress, to: ContractAddress, id: u256, value: u256) event

TransferBatch(operator: ContractAddress, from: ContractAddress, to: ContractAddress, ids: Span<u256>, values: Span<u256>) event

ApprovalForAll(owner: ContractAddress, operator: ContractAddress, approved: bool) event

URI(value: ByteArray, id: u256) event

参见 IERC1155::URI

接收者

IERC1155Receiver

use openzeppelin_token::erc1155::interface::IERC1155Receiver;

对于支持从 ERC1155 合约接收 token 转移的合约的接口。

0x15e8665b5af20040返回 IERC1155Receiver 接口 ID。

==== on_erc1155_batch_received(self: @ContractState, operator: ContractAddress, from: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data Span<felt252>) -> felt252 external

返回 IERC1155Receiver 接口 ID。

==== onERC1155Received(self: @ContractState, operator: ContractAddress, from: ContractAddress, tokenId: u256, value: u256, data Span<felt252>) -> felt252 external

==== onERC1155BatchReceived(self: @ContractState, operator: ContractAddress, from: ContractAddress, tokenIds: Span<u256>, values: Span<u256>, data Span<felt252>) -> felt252 external

==== 内部函数

==== initializer(ref self: ContractState) internal

通过内省注册 IERC1155Receiver 接口 ID 作为支持的接口。

== 预设

=== ERC1155Upgradeable

use openzeppelin_presets::ERC1155;

可升级的 ERC1155 合约,利用 ERC1155Component

{ERC1155Upgradeable-class-hash}

ERC1155Component
OwnableMixinImpl

==== 构造函数

==== constructor(ref self: ContractState, base_uri: ByteArray, recipient: ContractAddress, token_ids: Span<u256>, values: Span<u256>, owner: ContractAddress) constructor

设置所有 token 的 base_uri 并注册支持的接口。 将 token_ids token 的 values 铸造到 recipient。 分配 owner 作为具有升级权限的合约所有者。

要求:

  • to 要么是账户合约(支持 ISR C6),要么 支持 IERC1155Receiver 接口。

  • token_idsvalues 必须具有相同的长度。

==== 外部函数

==== upgrade(ref self: ContractState, new_class_hash: ClassHash) external

将合约升级到由 new_class_hash 给出的新实现。

要求:

  • 调用者是合约所有者。

  • new_class_hash 不能为零。