Mox Stablecoin

• A stablecoin built on the Mox framework.
• Supports various stablecoin functionalities.
• Built with a 4/1 ratio of collateral to stablecoin issuance.
• Designed for efficient and secure stablecoin operations.

Setup & Installation

• Install dependencies and create virtual environment.
• Import project into your IDE.
• Run tests to verify setup.

Prerequisites

• Python 3.11+
• uv (modern Python package manager)

Quick Start

# Clone and enter project
git clone <repo-url>
cd mox-stablecoin

# Install dependencies and create virtual environment
uv sync

# Activate virtual environment (optional, uv run handles this)
source .venv/bin/activate

# Run tests
uv run mox test

# Format code
just format

Development Workflow

• Use uv run for all commands to ensure proper environment isolation.
• Run uv sync after updating pyproject.toml
• Use just format for code formatting.
• Run mox test --coverage for testing with coverage.

Frontend

The project includes a minimal web frontend built with Vite + JavaScript that allows users to:

• View protocol statistics (total supply, deposited collateral)
• Check their account balances and health factor
• Deposit collateral (WETH/WBTC)
• Mint DSC tokens
• Redeem collateral
• Burn DSC tokens

Frontend Setup

# Install frontend dependencies
just setup-frontend

# Generate config with deployed contract addresses
just gen-frontend-config

# Start frontend development server
just dev-frontend

The frontend connects to your local Anvil network and provides a clean interface for interacting with the stablecoin protocol.

Testnet Deployment

Deploy the stablecoin protocol to Sepolia testnet for testing and demonstration.

Prerequisites

• Set up your Sepolia RPC URL in .env:

  SEPOLIA_RPC_URL=https://your-sepolia-rpc-url

• Fund your deployment account with Sepolia ETH (use faucets like https://sepoliafaucet.com/)

Deploy to Testnet

# Deploy to Sepolia testnet
uv run mox run script/deploy_testnet.py --network sepolia

# The deployment script will:
# - Deploy DSC token contract
# - Deploy DSC Engine contract
# - Configure price feeds and collateral tokens
# - Generate deployment info and frontend config

Post-Deployment

After deployment, the script creates DEPLOYMENT_INFO.md with:

• Contract addresses
• Network information
• Frontend configuration
• Next steps for testing

Update your frontend config and test the protocol on testnet!

Features

• Collateralized stablecoin issuance.
• Redemption of stablecoins for collateral.
• Price stability mechanisms.
• Integration with Mox ecosystem.
• Secure and transparent operations.

Purpose

• The purpose of this project is to demonstrate the capabilities of the Mox framework in building a stablecoin.
• It serves as a reference implementation for developers interested in creating stablecoins using Mox.
• The project aims to showcase best practices in smart contract development, security, and stablecoin economics.
• This is also a testing ground for new features and improvements in the Mox ecosystem.
• It is intended for educational and experimental use within the Mox community.
• Not intended for production use without further development and auditing.
• Users should exercise caution and conduct thorough testing before deploying in a live environment.

Testing- Comprehensive test suite included

• Unit tests for all major functionalities.
• Integration tests for end-to-end scenarios.
• Tests are located in the tests/ directory.
• For coverage tests run mox test --coverage --cov-report term-missing
• For full fuzz testing run mox test -s -k stablecoin_fuzzer

Fuzz Testing

• Fuzz testing is implemented using Snekmate.
• Fuzz tests are located in the tests/fuzz/ directory.
• The purpose of fuzz testing is to identify edge cases and potential vulnerabilities in the stablecoin logic.
• NOTE: Fuzz testing is an additional layer of testing and should be used in conjunction with unit and integration tests to ensure comprehensive coverage.
• NOTE: Fuzz testing may take significantly longer to run than standard tests.
• NOTE: There are a few tests built to specifically break the system (as the case here); passing all tests does not guarantee complete security.

Dev Notes

• Use uv run for all commands to ensure proper environment isolation.
• Run uv sync after updating pyproject.toml
• Use just format for code formatting.

Contributing

• Contributions are welcome!
• Please fork the repository and submit pull requests.
• Follow coding standards and include tests for new features!