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
返回从 accounts
和 token_ids
对派生的余额列表。
safe_transfer_from(from: ContractAddress, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>)
external
如果 to
是 IERC1155Receiver
或一个 account,则将 token_id
的 value
数量的所有权从 from
转移到 to
。
data
是附加数据,它没有指定的格式,并传递给 to
。
发出一个 TransferSingle 事件。
safe_batch_transfer_from(from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>)
external
如果 to
是 IERC1155Receiver
或一个 account,则将 token_ids
和 values
对的所有权从 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 通过 operator
从 from
转移到 to
时发出。
TransferBatch(operator: ContractAddress, from: ContractAddress, to: ContractAddress, ids: Span<u256>, values: Span<u256>)
event
当通过 operator
从 from
转移到 to
的一批 values
数量的 ids
tokens 时发出。
IERC1155MetadataURI
use openzeppelin_token::erc1155::interface::IERC1155MetadataURI;
EIP1155 中可选元数据函数的接口。
0xcabe2400d5fe509e1735ba9bad205ba5f3ca6e062da406f72f113feb889ef7
ERC1155Component
use openzeppelin_token::erc1155::ERC1155Component;
实现 IERC1155 和 IERC1155MetadataURI 的 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
返回从 accounts
和 token_ids
对派生的余额列表。
要求:
-
token_ids
和accounts
必须具有相同的长度。
safe_transfer_from(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_id: u256, value: u256, data: Span<felt252>)
external
如果 to
是一个 account 或 IERC1155Receiver
,则将 token_id
的 value
数量的所有权从 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
,则将 values
和 token_ids
对的所有权从 from
转移到 to
。
data
是附加数据,它没有指定的格式,并传递给 to
。
当将 tokens 转移到不受信任的合约时,此函数可能会允许重入攻击,当在接收者上调用 on_ERC1155_batch_received 时。确保遵循检查-效果-交互模式,并在与不受信任的合约交互时考虑使用重入保护。
|
要求:
-
调用者要么被批准,要么是
token_id
的 owner。 -
from
不是零地址。 -
to
不是零地址。 -
token_ids
和values
必须具有相同的长度。 -
如果
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。
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
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_ids
和values
必须具有相同的长度。 -
如果
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_ids
和values
必须具有相同的长度。
发出一个 TransferBatch 事件。
update_with_acceptance_check(ref self: ContractState, from: ContractAddress, to: ContractAddress, token_ids: Span<u256>, values: Span<u256>, data: Span<felt252>)
internal
update
的版本,它通过调用
onERC1155Received
或 onERC1155BatchReceived
在接收者中执行 token 接受检查,如果
它实现了 IERC1155Receiver
,否则通过检查它是否为一个 account。
要求:
-
to
要么是一个 account 合约,要么支持IERC1155Receiver
接口。 -
token_ids
和values
必须具有相同的长度。
如果数组包含一个元素,则发出一个 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_ids
和values
必须具有相同的长度。
如果数组包含一个元素,则发出一个 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
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 作为支持的接口。
== 预设
use openzeppelin_presets::ERC1155;
可升级的 ERC1155 合约,利用 ERC1155Component。
{ERC1155Upgradeable-class-hash}
==== 构造函数
==== 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_ids
和values
必须具有相同的长度。
==== 外部函数
==== upgrade(ref self: ContractState, new_class_hash: ClassHash)
external
将合约升级到由 new_class_hash
给出的新实现。
要求:
-
调用者是合约所有者。
-
new_class_hash
不能为零。