diff --git a/ecosystem/sep-1155.md b/ecosystem/sep-1155.md new file mode 100644 index 000000000..ce6df4cba --- /dev/null +++ b/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` + - `balance_of_batch(env: Env, accounts: Vec
, ids: Vec) -> Result, 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` + - **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, amounts: Vec) -> 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, amounts: Vec) -> Result<(), ContractError>` + - `burn(env: Env, from: Address, id: u64, amount: u64) -> Result<(), ContractError>` + - `burn_batch(env: Env, from: Address, ids: Vec, amounts: Vec) -> 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` + - **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` + - **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) +