# Tezos ERC-1155 smart contract specification

## Abstract

This document describes specification for Tezos ERC-1155 contract adapted from the
corresponding specification for [Ethereum](https://eips.ethereum.org/EIPS/eip-1155).
Token standards like ERC-20 and ERC-721 require a separate contract to be deployed for each
token type or collection. ERC-1155 contract manages multiple token types. A new token can be
created and configured without redeploying the contract. Both fungible and non-fungible tokens
can be stored in the same smart-contract.

## ERC-1155 overview

**Token type** is a specific token represented by its ID. **Owner** - Tezos address which can
hold tokens. **Operator** - Tezos address which initiates token transfer operation. **Operator**
must be approved to manage all tokens hold by the owner to make a transfer from the owner account.

Destination address for the token transfer operation MUST implement `ERC1155TokenReceiver` interface,
which MUST be called for transfer/mint transactions. Destination address may reject receiving
tokens by generating failure. This is considered a safety feature ("safe transfer") to prevent
unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens.

ERC-1155 supports both single token transfer and atomic batch transfer of multiple tokens.

Administrative operations to create new token types, mint and burn tokens are not part of ERC-1155
specification.

## Difference between Ethereum and Tezos

Since Tezos and Michelson differ from Ethereum/Solidity, the following modifications are made:

1. Tezos ERC-1155 does not emit events (a feature not supported by Tezos).
2. Tezos ERC-1155 does not implement ERC-165 `supportsInterface` entry point.
3. Ethereum specification says that if destination transfer address is not a smart contract
(Externally Owned Account),then safety check is not performed. Otherwise, if destination
contract does not implement `ERC1155TokenReceiver` interface, the transaction should fail.
Michelson does not provide API to distinguish between implicit (EOA) and originated addresses
since Babylon version. Tezos specification requires that safety check MUST be performed only
when target contract implements `ERC1155TokenReceiver` interface. Otherwise, safety check is skipped.
4. Ordering requirements for batch transfers is relaxed. Since Tezos smart contracts are referentially
transparent, batch order must be preserved only for invocation of `OnERC1155Received`/`OnERC1155BatchReceived`
entry points of `ERC1155TokenReceiver` interface.
5. Optional `ERC1155Metadata_URI` interface is not part of Tezos ERC-1155 specification.

## Specification

Specification is given as definition of Michelson entry points defined in [cameligo language](https://ligolang.org).
ERC-1155 specification consist of two interfaces: `erc1155` and `erc1155_token_receiver`.

** Smart contracts implementing the ERC-1155 standard protocol MUST implement all of the entry points
in the `erc1155` interface.**

** All smart contracts which can be a target destination for the token transfers MUST implement all of the
entry points in the `erc1155_token_receiver` interface.

### `erc1155` entry points

type token_id = nat

type safe_transfer_from_param = {
  from: address;      (* Source address *)
  to_:   address;     (* Target address. Target smart contract must implement entry points from `erc1155_receiver` interface *)
  token_id: token_id; (* ID of the token type *)
  amount: nat;        (* Transfer amount *)
  data: bytes;        (* Additional data with no specified format, MUST be sent unaltered in call to `On_erc1155_received` on `to_` *)
}

type tx = {
  token_id: token_id; (* ID of the token type *)
  amount: nat;        (* Transfer amount *)
}

type safe_batch_transfer_from_param = {
  from: address;      (* Source address *)
  to_:   address;     (* Target address. Target smart contract must implement entry points from `erc1155_receiver` interface *)
  batch: tx list;     (* Batch of tokens and their amounts to be transferred *)
  data: bytes;        (* Additional data with no specified format, MUST be sent unaltered in call to `On_erc1155_batch_received` on `to_` *)
}

type balance_request = {
  owner: address;     (* The address of the token holder *)
  token_id: token_id; (* ID of the  token *)
}

type balance_of_param = {
  balance_request: balance_request;
  balance_view: balance_request * nat -> operation;
}

type balance_of_batch_param = {
  balance_request: balance_request list;
  balance_view: balance_request * nat list -> operation;
}

type set_approval_for_all_param = {
  operator: address;  (* Address to add or remove from the set of authorized operators for sender *)
  approved: bool;     (* True if the operator is approved, false to revoke approval *)
}

type is_approved_for_all_request = {
  owner: address;     (* The owner of the tokens *)
  operator: address;  (* Address of authorized operator *)
}
type is_approved_for_all_param = {
  is_approved_for_all_request: is_approved_for_all_request;
  approved_view: is_approved_for_all_request * bool -> operation
}

(* ERC1155 entry points *)
type erc1155 =
  (*
    Transfers specified `amount` of an `token_id` from the `from` address to the `to_` address specified (with safety call).
    Caller must be approved to manage the tokens being transferred out of the `from` account (see "Approval" section of the standard).
    MUST revert if balance of holder for token `token_id` is lower than the `amount` sent.
    MUST call `On_erc1155_received` on `to_` and act appropriately (see "Safe Transfer Rules" section of the standard)
    if `to_` contract implements `erc1155_receiver` interface. Otherwise skips safety check.
  *)
  | Safe_transfer_from of safe_transfer_from_param
  (*
    Transfers specified `amount`(s) of `token_id`(s) from the `from` address to the `to_` address specified (with safety call).
    Caller must be approved to manage the tokens being transferred out of the `from` account (see "Approval" section of the standard).
    MUST revert if any of the balance(s) of the holder(s) for token(s) is lower than the respective amount(s) in `_values` sent to the recipient.
    MUST call the relevant `erc1155_token_receiver` hook(s) on `to_` and act appropriately (see "Safe Transfer Rules" section of the standard)
    if `to_` contract implements `erc1155_receiver` interface. Otherwise skips safety check.
  *)
  | Safe_batch_transfer_from of safe_batch_transfer_from_param
  (* Get the balance of an account's tokens. *)
  | Balance_of of balance_of_param
  (* Get the balance of multiple account/token pairs *)
  | Balance_of_batch of balance_of_batch_param
  (* Enable or disable approval for a third party ("operator") to manage all of the caller's tokens. *)
  | Set_approval_for_all of set_approval_for_all_param
  (* Queries the approval status of an operator for a given owner. *)
  | Is_approved_for_all of is_approved_for_all_param

#### `Safe_transfer_from` Rules

Transfers specified `amount` of `token_id` from `from` address to `to_` address.

Sender MUST be approved to manage the tokens being transferred out of the `from` account or be the same address as `from`
address (see "Approval" section of the standard). Otherwise the transaction should fail.

The transaction MUST fail if balance of holder for token `token_id` is lower than the `amount` sent. If
holder does not hold any tokens of type `token_id`, holder's balance is interpreted as zero.

The transaction MUST call entry point `On_erc1155_received` or `On_erc1155_batch_received` of contract `to_` and MUST return
call `operation` among other operations it might create. If `to_` contract does not implement entry point `On_erc1155_received`,
the transaction MUST skip safety check. `data` argument must be passed unaltered to a receiver hook entry point. A contract MAY skip calling
the `On_erc1155_received` hook function if the transfer operation is transferring the token to itself.

#### `Safe_batch_transfer_from` Rules

Transfers specified amounts between addresses specified in the batch. Transfers should happen atomically: if at least one
specified transfer cannot be completed, the whole transaction MUST fail.

Sender MUST be approved to manage the tokens being transferred out of the `from` account or be the same address as `from`
address (see "Approval" section of the standard). Otherwise the transaction should fail.

The transaction MUST fail if any of the balance(s) of the holder for token(s) in the batch is lower than the respective
amount(s) sent. If holder does not hold any tokens of type `token_id`, holder's balance is interpreted as zero.

The transaction MUST call entry point `On_erc1155_batch_received` or `On_erc1155_received` of contract `to_` and MUST return
call `operation` among other operations it might create. If `to_` contract does not implement entry point `On_erc1155_received`,
the transaction MUST skip safety check. `data` argument must be passed unaltered to a receiver hook entry point.
`On_erc1155_batch_received` and `On_erc1155_received` MAY be called multiple times from the transaction in any combination and
the following requirements must be met:

* All calls must represent mutually exclusive balance changes.
* The set of all calls to `On_erc1155_received` and `On_erc1155_batch_received` describes all balance changes that occurred during
the transaction in the order submitted.
* A contract MAY skip calling the `On_erc1155_received` hook function if the transfer operation is transferring the token to itself.

#### `Balance_of`

Get the balance of an account's tokens. `balance_request` parameter has `balance_request.owner` address and `balance_request.token_id`.
The entry point parameters are `balance_request` and callback lambda `balance_view` which accepts a pair of `balance_request` and
corresponding balance.

#### `Balance_of_batch`

Get the balance of multiple account/token pairs. Accepts a list of `balance_request`s and callback lambda which accepts a list of pairs of
`balance_request` and balance.

#### Approval

The entry point `Set_approval_for_all` allows an operator to manage one’s entire set of tokens on behalf of the approver. To permit approval
of a subset of token IDs, an interface such as [ERC-1761 Scoped Approval Interface](https://eips.ethereum.org/EIPS/eip-1761) is suggested.
The counterpart `Is_approved_for_all` provides introspection into any status set by `Set_approval_for_all`.

An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to
call `Set_approval_for_all` to approve themselves as an operator before they can operate on them.

#### Minting/creating and burning/destroying rules

A mint/create operation is essentially a specialized transfer and MUST follow safe transfer rules in regard of invoking `On_erc1155_received`
and `On_erc1155_batch_received` for the contract which receives minted tokens.

### `erc1155_token_receiver` entry points

type on_erc1155_received_param = {
  operator: address;    (* The address which initiated the transfer (i. e. sender) *)
  from: address option; (* Source address. None for minting operation *)
  token_id: token_id;   (* ID of the token type *)
  amount: nat;          (* Transfer amount *)
  data: bytes;          (* Additional data with no specified format *)
}

type on_erc1155_batch_received_param = {
  operator: address;    (* The address which initiated the transfer (i. e. sender) *)
  from: address option; (* Source address. None for minting operation *)
  batch: tx list;       (* Batch of tokens and their amounts which are transferred *)
  data: bytes;          (* Additional data with no specified format *)
}

(* ERC1155TokenReceiver entry points *)
type erc1155_token_receiver =
  (*
    Handle the receipt of a single ERC1155 token type.
    An ERC1155-compliant smart contract MUST call this function on the token recipient
    contract from a `Safe_transfer_from`.
    MUST revert if it rejects the transfer.
  *)
  | On_erc1155_received of on_erc1155_received_param
  (*
    Handle the receipt of multiple ERC1155 token types.
    An ERC1155-compliant smart contract MUST call this function on the token recipient
    contract from a `Safe_batch_transfer_from`.
    MUST revert if it rejects the transfer(s).
  *)
  | On_erc1155_batch_received of on_erc1155_batch_received_param

#### `erc1155_token_receiver` Rules

If an implementation specific API function is used to transfer ERC-1155 token(s) to a contract,
the `Safe_transfer_from`or `Safe_batch_transfer_from` (as appropriate) rules MUST still be followed
and the receiver MUST implement the `erc1155_token_receiver` interface.

Only non-standard transfer functions MAY allow tokens to be sent to a recipient contract that
does NOT implement the necessary `erc1155_token_receiver` hook functions.