SEP-1155: Multi Token Standard

ecosystem/sep-1155.md

@@ -0,0 +1,123 @@
+## Preamble
+
+```
+SEP: 1155
+Title: Multi Token Standard
+Author: Jakub Bogucki (@ueco-jb)
+Track: Standard
+Status: Draft
+Created: 29.08.2024
+Updated: 29.08.2024
+Version: 0.1.0
+```
+
+## Simple Summary
+This proposal introduces a Soroban smart contract that mirrors the ERC1155 multi token standard on Stellar. The contract will enable the creation, management, and transfer of multiple token types within a single contract instance, allowing for more versatile token management within the Stellar ecosystem.
+
+## Dependencies
+- `soroban_sdk`
+
+## Motivation
+The existing Stellar token standards focus on single-asset management, limiting their utility for applications that require managing multiple token types. Implementing a Multi Token Standard on Stellar will enable a more versatile token management system, supporting various use cases such as gaming, collectibles, and multi-asset trading platforms.
+
+## Abstract
+This SEP proposes an multi-token standard implementation for Stellar using Soroban smart contracts. The contract allows the creation, transfer, and management of multiple token types within a single contract instance, similar to the ERC1155 standard on Ethereum. This functionality will enhance Stellar's capabilities to support diverse applications, such as gaming, NFTs, and multi-asset trading platforms, by providing a flexible and efficient token management system.
+
+## Specification
+The ERC1155 equivalent contract for Stellar using Soroban smart contracts will include the following core functionalities:
+
+1. **Initialization (`initialize`)**:
+   - **Function Signature**: `initialize(env: Env, admin: Address, name: String, symbol: String) -> Result<(), ContractError>`
+   - **Description**: Initializes the contract with an administrator, a name, and a symbol. This function must only be callable once and sets up the basic configuration and permissions for the contract.
+   - **Events**:
+     - `initialize`: Logs the initialization of the contract with the collection name and symbol.
+
+2. **Balance Query (`balance_of` and `balance_of_batch`)**:
+   - **Function Signature**:
+     - `balance_of(env: Env, account: Address, id: u64) -> Result<u64, ContractError>`
+     - `balance_of_batch(env: Env, accounts: Vec<Address>, ids: Vec<u64>) -> Result<Vec<u64>, ContractError>`
+   - **Description**:
+     - `balance_of`: Returns the balance of a specific token ID for a given account.
+     - `balance_of_batch`: Returns the balances of multiple token IDs for multiple accounts.
+   - **Events**: None.
+
+3. **Approval Management (`set_approval_for_all` and `is_approved_for_all`)**:
+   - **Function Signature**:
+     - `set_approval_for_all(env: Env, sender: Address, operator: Address, approved: bool) -> Result<(), ContractError>`
+     - `is_approved_for_all(env: Env, owner: Address, operator: Address) -> Result<bool, ContractError>`
+   - **Description**:
+     - `set_approval_for_all`: Grants or revokes permission to an operator to manage all tokens of the caller.
+     - `is_approved_for_all`: Checks if an operator is approved to manage all tokens of a specific owner.
+   - **Events**:
+     - `set_approval_for_all`: Logs the approval or revocation of an operator's permissions.
+
+4. **Token Transfers (`safe_transfer_from` and `safe_batch_transfer_from`)**:
+   - **Function Signature**:
+     - `safe_transfer_from(env: Env, from: Address, to: Address, id: u64, transfer_amount: u64) -> Result<(), ContractError>`
+     - `safe_batch_transfer_from(env: Env, from: Address, to: Address, ids: Vec<u64>, amounts: Vec<u64>) -> Result<(), ContractError>`
+   - **Description**:
+     - `safe_transfer_from`: Safely transfers a specified amount of a token ID from one account to another, checking for authorization and sufficient balance.
+     - `safe_batch_transfer_from`: Safely transfers multiple token types and amounts from one account to another.
+   - **Events**:
+     - `safe_transfer_from`: Logs the transfer of tokens, including the sender, receiver, token ID, and amount.
+     - `safe_batch_transfer_from`: Logs the batch transfer of tokens.
+
+5. **Token Minting and Burning (`mint`, `mint_batch`, `burn`, and `burn_batch`)**:
+   - **Function Signature**:
+     - `mint(env: Env, sender: Address, to: Address, id: u64, amount: u64) -> Result<(), ContractError>`
+     - `mint_batch(env: Env, sender: Address, to: Address, ids: Vec<u64>, amounts: Vec<u64>) -> Result<(), ContractError>`
+     - `burn(env: Env, from: Address, id: u64, amount: u64) -> Result<(), ContractError>`
+     - `burn_batch(env: Env, from: Address, ids: Vec<u64>, amounts: Vec<u64>) -> Result<(), ContractError>`
+   - **Description**:
+     - `mint`: Creates a specified amount of tokens of a given ID and assigns them to a specified account.
+     - `mint_batch`: Mints multiple types and amounts of tokens and assigns them to a specified account.
+     - `burn`: Destroys a specified amount of tokens of a given ID from a specified account.
+     - `burn_batch`: Destroys multiple types and amounts of tokens from a specified account.
+   - **Events**:
+     - `mint`: Logs the minting of tokens, including the minter, recipient, token ID, and amount.
+     - `mint_batch`: Logs the batch minting of tokens.
+     - `burn`: Logs the burning of tokens, including the owner, token ID, and amount.
+     - `burn_batch`: Logs the batch burning of tokens.
+
+6. **Metadata Management (`set_uri` and `uri`)**:
+   - **Function Signature**:
+     - `set_uri(env: Env, sender: Address, id: u64, uri: Bytes) -> Result<(), ContractError>`
+     - `uri(env: Env, id: u64) -> Result<URIValue, ContractError>`
+   - **Description**:
+     - `set_uri`: Sets a URI for a specific token type.
+     - `uri`: Retrieves the URI associated with a specific token type.
+   - **Events**:
+     - `set_uri`: Logs the setting of a URI for a token type.
+
+7. **Collection Metadata Management (`set_collection_uri` and `collection_uri`)**:
+   - **Function Signature**:
+     - `set_collection_uri(env: Env, uri: Bytes) -> Result<(), ContractError>`
+     - `collection_uri(env: Env) -> Result<URIValue, ContractError>`
+   - **Description**:
+     - `set_collection_uri`: Sets a URI for the entire collection managed by the contract.
+     - `collection_uri`: Retrieves the URI associated with the entire collection.
+   - **Events**:
+     - `set_collection_uri`: Logs the setting of a URI for the collection.
+
+8. **Contract Upgrades (`upgrade`)**:
+   - **Function Signature**: `upgrade(env: Env, new_wasm_hash: BytesN<32>) -> Result<(), ContractError>`
+   - **Description**: Allows the contract administrator to upgrade the contract logic while retaining state.
+   - **Events**:
+     - `upgrade`: Logs the upgrade of the contract with the new WASM hash.
+
+
+## Design Rationale
+The design of the standard on Stellar using Soroban smart contracts was guided by the following considerations:
+- Multi-token Management: The standard allows multiple token types to be managed within a single contract, reducing the complexity and cost associated with deploying multiple contracts.
+- Flexibility: The contract supports both fungible and non-fungible tokens, making it suitable for a wide range of applications from gaming to NFTs.
+- Efficiency: By using a single contract to manage multiple token types, the implementation reduces the operational overhead and improves the scalability of applications on Stellar.
+
+## Security Concerns
+The following security concerns must be addressed:
+1. Reentrancy: Ensure that no reentrancy attacks are possible by carefully managing state changes and external calls
+2. Overflow and Underflow: Use safe arithmetic operations to prevent overflow and underflow vulnerabilities in token calculations.
+3. Upgradeability: Safeguard the upgrade functionality to prevent unauthorized contract changes and maintain data integrity.
+
+## Changelog
+- `v0.1.0`: Initial draft. [#1538](https://github.com/stellar/stellar-protocol/pulls/1538)
+