# OpenALCHI Documentation

## Introduction

Welcome to OpenALCHI, a revolutionary project that combines the fascinating world of alchemy with the latest advancements in blockchain technology. OpenALCHI offers a unique gaming experience where users can discover, mint, and trade elemental NFTs. Our platform leverages the power of decentralized finance (DeFi) to create a vibrant ecosystem where users can explore, interact, and benefit from various elements within the game.

## Project Overview

**User-Generated Elements**

* **Feature Description**: Users can now submit elements to the game by paying a submission fee. These elements include a rarity level (ranging from 1 to 10) and are automatically marked as "discovered" upon creation.
* **How it Works**:
  * Users call the `submitElement` function, passing a `rarity` parameter.
  * A submission fee is required, which is transferred to the `fundAddress`.
  * Each user-created element is assigned a unique ID and marked with the creator's address.

**User-Generated Combinations**

* **Feature Description**: Users can propose new combinations of existing elements by linking two input elements to a resulting element.
* **How it Works**:
  * The function `submitCombination` verifies that the input and output elements exist and are discovered.
  * Only the creator of the result element (or the owner, for system-generated elements) can submit combinations using it.

**Royalty System**

* **Feature Description**: Users who create new elements earn royalties whenever their elements are minted through combinations.
* **How it Works**:
  * A percentage of the combination fee (defined by `royaltyPercentage`) is allocated to the element creator.
  * Royalties can be claimed using the `claimRoyalties` function, which transfers the accumulated royalties to the creator's address.

**AI-Generated Elements**

* **Feature Description**: Future integration of AI-generated elements, allowing for dynamic and innovative additions to the ecosystem. The contract currently supports marking elements as user-created or system-generated, enabling flexibility for future AI integration.

**IPFS Integration**

* **Feature Description**: The metadata and images for elements are stored on IPFS for decentralized and secure access.
* **How it Works**:
  * The `uri` function returns the IPFS path for an element's metadata based on its token ID.
  * Each metadata file is expected to follow the structure `[baseURI]/[tokenId].json`.

**Migration Support for Combinations**

* **Feature Description**: A migration function is available to convert the old combination format into a more optimized structure.
* **How it Works**:
  * The `migrateCombinations` function populates the `combinationList` array, which stores all combinations in a structured format.
  * This ensures compatibility with future updates and easier querying of combinations.

**Fee Structures**

* **Element Submission Fee**: Configurable by the owner through the `setElementSubmissionFee` function. This fee is required for creating new elements.
* **Combination Fee**: Based on the rarity of the resulting element and calculated using the `calculateFee` function.

**Creator-Focused Features**

* **View Creator Elements**: Users can retrieve all elements created by a specific address using the `getCreatorElements` function.
* **Royalty Details**: Users can check their royalty status and accumulated balance via the `getCreatorRoyalties` function.

**Additional Utility Functions**

* **Combination Query**: Use `getAllCombinations` to fetch all existing combinations.
* **Combination Existence Check**: Use `hasCombination` to verify if a combination exists between two elements.

## Smart Contracts

OpenALCHI is powered by several smart contracts, each serving a specific purpose within the ecosystem:

1. **AlchemyGame.sol**: Manages the core game mechanics, including element minting and combination discovery.\
   \&#xNAN;*Audit Report:* [View the audit of the AlchemyGame contract](https://api.auditbase.com/reports/875d4c2f-0253-4fed-a3d7-dd4500911ef9/public/pdf?team_id=378915d7-cf14-4040-a389-fedd690ffe62)
2. **NFTStake.sol**: Handles the staking of NFTs, allowing users to earn rewards over time.
3. **OpenMarketplace.sol**: Facilitates the buying, selling, and trading of elements in the marketplace.
4. **Token.sol**: Represents the community tokens.

##