⚗️ Alchemy Guild

NFT Staking Meets Yield Alchemy

📖 Overview

Alchemy Guild is a DeFi yield generation platform that combines NFT staking with automated Uniswap V3 liquidity provision. Mint elemental NFTs, stake them in the Yield Vault, and earn USDC from trading fees.

🎯 Key Features

🔮 Elemental NFTs: Three rarity tiers (Fire, Water, Earth) with different staking weights
💰 Automated Yield: Earn USDC from Uniswap V3 trading fees
⚡ Instant Claims: 20% USDC reserve ensures immediate reward payouts
🎨 Beautiful UI: Alchemical-themed interface with stunning animations
🤖 24/7 Bot: Autonomous bot generates volume and manages liquidity

📊 Current Stats

Metric	Value
Status	✅ Production Ready
Efficiency	~60% (USDC fees only)
Network	Ethereum Sepolia Testnet
Rebalance Success Rate	100%
Active Positions	#223170

🏗️ Architecture

graph TD
    A[User] -->|Mint NFT| B[ElementNFT Contract]
    B -->|Stake| C[YieldVault Contract]
    C -->|Provide Liquidity| D[Uniswap V3 WETH/USDC Pool]
    D -->|Trading Fees| C
    C -->|Distribute USDC| A
    E[Volume Bot] -->|Rebalance| C
    E -->|Generate Volume| D
    C -->|10% Tax| F[Treasury]

Core Components

Component	Description
ElementNFT	ERC-721 collection with 3 tiers and evolution mechanics
YieldVault	Automated Uniswap V3 LP manager & yield distributor
Alchemist	NFT crafting & evolution system
Treasury	Receives 10% protocol tax
Volume Bot	Generates trading volume & triggers rebalances

🚀 Quick Start

Prerequisites

Node.js 18+
Foundry (for contracts)
MetaMask wallet
Sepolia ETH & USDC

Installation

# Clone the repository
git clone https://github.com/tmalone1250/alchemy-guild.git
cd alchemy-guild

# Install dependencies
npm install

# Copy environment file
cp .env.example .env
# Add your PRIVATE_KEY and VITE_INFURA_RPC_URL

# Start development server
npm run dev

Running the Bot

# Ensure .env is configured
npx tsx volume-bot.ts

📝 Deployed Contracts (Sepolia)

Contract	Address	Verified
ElementNFT	`0xF15e4954AE325d68BFF9c990F26269D9c024caF0`	✅
YieldVault	`0xFff8e4da589f15453e73004b65c61Da341B9075C`	✅
Alchemist	`0x8f392ccee00369d6623e18E6DDF120E988f3a513`	✅
Treasury	`0x09b6E39f11C4c26022D10DE50d63C0541ad40227`	✅

External Contracts

WETH: 0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14
USDC: 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
Uniswap V3 Pool: 0x6Ce0896eAE6D4BD668fDe41BB784548fb8F59b50

💎 The Elemental Hierarchy

Alchemy Guild features 18 unique elements across three tiers, each with distinct staking power and yield potential.

Tier Classification

Tier	Classification	Reward Weight	Elements	Border Color
Tier 1	� Lead (Base Elements)	10	6 elements	Bronze
Tier 2	⚪ Silver (Advanced Synthesis)	30	6 elements	Silver
Tier 3	🟡 Gold (Transcendent)	100	6 elements	Gold

Complete Element Matrix

Tier 1 (Lead)	Tier 2 (Silver)	Tier 3 (Gold)
🌍 Earth 💧 Water 💨 Wind 🔥 Fire ❄️ Ice ⚡ Lightning	⚛️ Plasma 🌪️ Tornado 🌨️ Blizzard 🌊 Tsunami 🏔️ Quake 🌋 Inferno	✨ Holy 🌑 Dark 🌀 Gravity ⏰ Time 🧬 Bio 👻 Spirit

⚗️ The Crafting Lab (Transmutation)

Transform lower-tier NFTs into higher-tier ones through alchemical fusion. All crafting requires a 0.002 ETH transmutation cost.

The Lead Synthesis (Tier 1 → Tier 2)

Combine 3 Tier 1 NFTs to create 1 Tier 2 NFT.

Example Recipes:

💧💧💨 Water + Water + Wind → 🌊 Tsunami
💨❄️❄️ Wind + Ice + Ice → 🌨️ Blizzard
🌍🌍🔥 Earth + Earth + Fire → 🏔️ Quake
💧⚡⚡ Water + Lightning + Lightning → ⚛️ Plasma

The Golden Ritual (Tier 2 → Tier 3)

Combine 3 Tier 2 NFTs to create 1 Tier 3 NFT.

Example Recipes:

🌊🌨️🌨️ Tsunami + Blizzard + Blizzard → ⏰ Time
🌋🌋🔥 Inferno + Inferno + Fire → 👻 Spirit
🌪️🌪️⚡ Tornado + Tornado + Lightning → ✨ Holy

Crafting Mechanics

function craft(uint256[3] tokenIds) external payable {
    require(msg.value >= 0.002 ether, "Transmutation fee required");
    // Burns 3 NFTs → Mints 1 higher-tier NFT
}

Key Features:

✅ 3-to-1 Ratio: Burn 3 lower-tier → Create 1 higher-tier
✅ Deflationary: Reduces total supply with each craft
✅ Specific Recipes: Each Tier 2/3 element requires exact ingredient combinations
✅ Protocol Fee: 0.002 ETH per transmutation

📈 Yield Dynamics & Weight Mathematics

How Rewards Are Calculated

Yields are distributed pro-rata based on each NFT's staking weight:

$$ Reward_{user} = \frac{Weight_{user}}{\sum Weight_{total}} \times Fees_{harvested} $$

Where:

$Weight_{user}$ = Sum of all staked NFT weights for the user
$\sum Weight_{total}$ = Total weight of all staked NFTs in the vault
$Fees_{harvested}$ = USDC fees collected from Uniswap trading

Weight Multipliers

Tier	Weight	Relative Earning Power
Tier 1	10	1x baseline
Tier 2	30	3x more than Tier 1
Tier 3	100	10x more than Tier 1

Example Scenario

Vault State:

User A: 1× Tier 3 (Gold) NFT = 100 weight
User B: 3× Tier 2 (Silver) NFTs = 90 weight
User C: 10× Tier 1 (Lead) NFTs = 100 weight
Total Weight: 290

Fees Collected: 100 USDC (after 10% tax to Treasury)

Distribution:

User A: $(100/290) \times 100 = 34.48$ USDC
User B: $(90/290) \times 100 = 31.03$ USDC
User C: $(100/290) \times 100 = 34.48$ USDC

Key Insight: User A earns the same as User C, but with 1 NFT vs 10 NFTs!

Deflationary Scarcity

Every crafting operation burns 3 NFTs to create 1:

Total supply decreases by 2 NFTs per craft
Higher-tier NFTs become increasingly scarce
Remaining stakers capture more yield per NFT over time

$$ Supply_{new} = Supply_{old} - 2 $$

This creates a flywheel effect:

Users craft to increase individual weight
Total NFT supply decreases
Yield per NFT increases for all stakers
Higher-tier scarcity drives value

🎮 Usage

For Users

Mint an NFT
- Connect wallet
- Approve USDC
- Select tier (1/2/3)
- Mint NFT
Stake NFT
- Navigate to Vault page
- Click "Stake" on your NFT
- Confirm transaction
Claim Yields
- Wait for rebalances (~5 min cycles)
- View pending rewards
- Click "Claim" to receive USDC

For Developers

Deploy Contracts

cd alchemy-vault
forge build
forge script script/DeployAlchemy.s.sol \
  --rpc-url $VITE_INFURA_RPC_URL \
  --broadcast \
  --private-key $PRIVATE_KEY

Seed Vault

npx tsx manual-seed.ts

Utility Scripts

Script	Purpose
`wrap-eth.ts`	Convert ETH → WETH
`swap-weth-usdc.ts`	Swap WETH → USDC
`check-rewards.ts`	View reward accumulation
`test-rebalance.ts`	Test rebalance function
`diagnose-rebalance.ts`	Full diagnostic

🛠️ Tech Stack

Smart Contracts

Solidity 0.8.26
Foundry (Forge, Cast, Anvil)
OpenZeppelin Contracts
Uniswap V3 Core & Periphery

Frontend

React 18 + TypeScript
Vite 5.x
Ethers.js 6.x
RainbowKit + Wagmi
TailwindCSS
Lucide Icons

Infrastructure

Infura (RPC)
Etherscan (Verification)
IPFS (Metadata)

🐛 Known Issues & Solutions

Issue	Impact	Status	Workaround
WETH→USDC swap fails in rebalance	40% lower yield	🔄 Investigating	Try-catch wrapper prevents crashes
WETH fees accumulate	Not distributed	⏳ Planned	Manual swap available
Testnet liquidity	Low fees	ℹ️ Expected	Normal for Sepolia

🏆 Major Bugs Fixed

Click to expand debugging history

1. Token Ordering Bug ✅

Issue: WETH and USDC reversed in Uniswap calls
Fix: Corrected to USDC=token0, WETH=token1

2. Incorrect Uniswap Addresses ✅

Issue: Wrong Sepolia addresses in deployment
Fix: Updated Position Manager and Swap Router

3. Fee Calculation Logic ✅

Issue: Three bugs in fee distribution
Fix: Aligned all variables with token0/token1 ordering

4. WETH Swap Failures ✅ (Mitigated)

Issue: Swap reverts during rebalance
Fix: Try-catch wrapper, accumulates WETH safely

5. ClaimYield Balance Issue ✅

Issue: USDC locked in Uniswap position
Fix: 20% USDC reserve + balance cap

6. Vault Address Mixup ✅

Issue: Bot using wrong contract address
Fix: Updated to correct YieldVault address

🔮 Roadmap

Short Term

Fix WETH swap in rebalance context
Increase vault liquidity for higher yields
Gas optimization
Enhanced event logging

Long Term

Mainnet Deployment - Real USDC yields
Multi-Pool Support - ETH/DAI, WBTC/ETH
NFT Marketplace - Trade staked positions
Governance DAO - Community parameter control
Advanced Crafting - Complex evolution recipes

📸 Screenshots

Landing Page

Dashboard

Inventory

The Vault (Staking)

The Lab (Crafting)

Analytics

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Uniswap V3 - Decentralized trading protocol
OpenZeppelin - Secure smart contract library
Foundry - Blazing fast Ethereum toolkit
RainbowKit - Best wallet connection UX

📞 Contact

Project Maintainer: @tmalone1250

Bot Wallet: 0xd83B5031506039893BF1C827b0A79aDDee71E1fE

Built with ⚗️ by Alchemy Guild

Transmuting Base Assets into Gold

⬆ back to top

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
docs		docs
public		public
src		src
.env		.env
.gitignore		.gitignore
ALCHEMY-GUILD-OVERVIEW.md		ALCHEMY-GUILD-OVERVIEW.md
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
DeployAlchemy.s.sol		DeployAlchemy.s.sol
README.md		README.md
analyze-tx.ts		analyze-tx.ts
bun.lockb		bun.lockb
check-all-staked.ts		check-all-staked.ts
check-bot-balances.ts		check-bot-balances.ts
check-claim-history.ts		check-claim-history.ts
check-global-state.ts		check-global-state.ts
check-mempool.ts		check-mempool.ts
check-ownership-quick.ts		check-ownership-quick.ts
check-ownership.ts		check-ownership.ts
check-pool.ts		check-pool.ts
check-position-behavior.ts		check-position-behavior.ts
check-position-details.ts		check-position-details.ts
check-position.ts		check-position.ts
check-rebalance-history.ts		check-rebalance-history.ts
check-reward-debt.ts		check-reward-debt.ts
check-rewards.ts		check-rewards.ts
check-vault-balance.ts		check-vault-balance.ts
check-vault-state-full.ts		check-vault-state-full.ts
check-vault-state.ts		check-vault-state.ts
claim-history.txt		claim-history.txt
components.json		components.json
debug-bot.ts		debug-bot.ts
debug-rebalance-final.ts		debug-rebalance-final.ts
debug-vault.ts		debug-vault.ts
detailed-vault-state.ts		detailed-vault-state.ts
diagnose-rebalance.ts		diagnose-rebalance.ts
diagnose-reward-debt.ts		diagnose-reward-debt.ts
eslint.config.js		eslint.config.js
find-deployment-block.ts		find-deployment-block.ts
find-staked-nfts.ts		find-staked-nfts.ts
get-usdc.ts		get-usdc.ts
index.html		index.html
landing_page.txt		landing_page.txt
manual-seed.ts		manual-seed.ts
manual-swap.ts		manual-swap.ts
package-lock.json		package-lock.json
package.json		package.json
pool-status.txt		pool-status.txt
postcss.config.js		postcss.config.js
quick-balance-check.ts		quick-balance-check.ts
quick-vault-check.ts		quick-vault-check.ts
read-vault-check.js		read-vault-check.js
rebalance-history.txt		rebalance-history.txt
reward-debt-diagnostic.txt		reward-debt-diagnostic.txt
setup-bot-funds.ts		setup-bot-funds.ts
simple-vault-check.ts		simple-vault-check.ts
swap-weth-usdc.ts		swap-weth-usdc.ts
tailwind.config.ts		tailwind.config.ts
test-rebalance.ts		test-rebalance.ts
test-swap-diagnostic.ts		test-swap-diagnostic.ts
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
unwrap-weth.ts		unwrap-weth.ts
vault-check.txt		vault-check.txt
vault-diagnostic.txt		vault-diagnostic.txt
vercel.json		vercel.json
verify-no-drainage.ts		verify-no-drainage.ts
verify-vault-params.ts		verify-vault-params.ts
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts
volume-bot.ts		volume-bot.ts
wrap-eth.ts		wrap-eth.ts

Tmalone1250/alchemy-guild

Folders and files

Latest commit

History

Repository files navigation