JuiceDollar (JUSD)

An oracle-free, collateralized stablecoin forked from dEURO

This repository contains the smart contracts for JuiceDollar (JUSD), a decentralized stablecoin system with native protocol shares (JUICE).

Links:

• Public Frontend
• Documentation
• Upstream Repository (d-EURO)
• Original Frankencoin (dEURO was forked from Frankencoin commit a2ce625, December 2, 2024)

Table of Contents

• Smart Contracts Overview
• Fork History
• Key Differences
• Audit Reports
• Development Setup
• Testing
• Deployment
• NPM Package
• Foundry Fuzzing Tests

Smart Contracts Overview

All source code is located in the contracts folder.

Core Contracts

| Contract | Description | |----------|-------------| | JuiceDollar.sol | The JUSD ERC20 stablecoin token | | Equity.sol | The JUICE ERC20 token (Juice Protocol) | | Leadrate.sol | Leading interest rate module for the system |

Minting Hub V2

| Contract | Description | |----------|-------------| | MintingHub.sol | Oracle-free collateralized minting system | | Position.sol | Individual collateralized loan position | | PositionFactory.sol | Factory to create new positions | | PositionRoller.sol | Roll positions into new ones |

Savings & Bridges

| Contract | Description | |----------|-------------| | Savings.sol | Interest distribution to JUSD holders | | SavingsVaultJUSD.sol | ERC4626 vault for JUSD savings | | StablecoinBridge.sol | 1:1 swaps with external stablecoins (StartUSD for bootstrap) |

Gateway Contracts (Frontend Rewards)

| Contract | Description | |----------|-------------| | FrontendGateway.sol | Rewards frontend providers for referrals | | MintingHubGateway.sol | Minting with frontend provider rewards | | SavingsGateway.sol | Savings with frontend provider rewards | | CoinLendingGateway.sol | Native coin (cBTC) lending with custom liquidation |

Fork History

JuiceDollar is part of a three-generation fork chain:

Frankencoin-ZCHF (Original)
    ↓
d-EURO (December 2024 fork)
    ↓
JuiceDollar (Current repository)

Upstream: d-EURO/smartContracts Origin: Frankencoin-ZCHF/FrankenCoin

Deployment Networks:

• Frankencoin-ZCHF: Ethereum Mainnet (native currency: ETH)
• dEURO: Ethereum Mainnet (native currency: ETH) | Testnet: Sepolia
• JuiceDollar: Citrea Mainnet (native currency: cBTC) | Testnet: Citrea Testnet

d-EURO forked from Frankencoin at commit a2ce625 (December 2, 2024), introducing significant protocol improvements. JuiceDollar continues this evolution with deployment on Citrea, using cBTC as the native currency.

Audit Reports

JuiceDollar inherits security audits from its upstream repositories:

Frankencoin Audits

| Date | Auditor | Report | |------|---------|--------| | 2023-02-10 | Blockbite | Report | | 2023-06-09 | Code4rena | Report | | 2023-10-30 | ChainSecurity | Report | | 2024-09-25 | Decurity | Report | | 2024-11-28 | ChainSecurity | Report |

dEURO-Specific Audits

| Auditor | Scope | Report | |---------|-------|--------| | ChainSecurity | dEURO fork changes (Interest Accrual, Auction, Accounting) | Audit | | Audit Boutique | dEURO smart contracts | Report PDF |

Bug Bounty

• JuiceDollar Bug Bounty: Program details will be announced soon
• Upstream Bug Bounty Programs:
  • Frankencoin Bug Bounty
  • dEURO Bug Bounty

Development Setup

Prerequisites

• Node.js & Yarn
• Hardhat
• (Optional) Foundry for fuzzing tests

1. Install Dependencies

yarn install

2. Environment Configuration

Create a .env file (see .env.example):

# Required: Deployer wallet private key
DEPLOYER_PRIVATE_KEY=your_private_key_here

# Optional: For contract verification on Citrea explorer
# CITREA_EXPLORER_API_KEY=your_api_key_here

3. Compile Contracts

yarn run compile

Testing

Run Tests

yarn run test                        # Run all tests
yarn run test test/TESTSCRIPT.ts    # Run specific test
yarn run coverage                   # Generate coverage report

Auto-refresh Testing

npx tsc-watch --onCompilationComplete "npx hardhat test ./test/RollerTests.ts"

Deployment

Target Networks

• Mainnet: Citrea (native currency: cBTC)
• Testnet: Citrea Testnet

Manual Deployment (Hardhat Deploy)

Deploy to Citrea Testnet:

hh deploy --network citreaTestnet --tags MockTokens
hh deploy --network citreaTestnet --tags JuiceDollar
hh deploy --network citreaTestnet --tags PositionFactory
hh deploy --network citreaTestnet --tags MintingHub
hh deploy --network citreaTestnet --tags positions

Testing on local fork:

# Set USE_FORK=true in .env, then:
npx hardhat node

Deploy Stablecoin Bridges

NOTE: The bootstrap bridge (StartUSD → JUSD) is deployed automatically via deployProtocol.ts

For additional bridges:

# 1. Add bridge config to scripts/deployment/config/stablecoinBridgeConfig.ts
# 2. Deploy using BRIDGE_KEY environment variable:
BRIDGE_KEY=<KEY> npx hardhat run scripts/deployment/deploy/deployBridge.ts --network citrea

# Test on forked network
USE_FORK=true BRIDGE_KEY=<KEY> npx hardhat run scripts/deployment/deploy/deployBridge.ts --network hardhat

Bridge configurations: scripts/deployment/config/stablecoinBridgeConfig.ts

Hardhat Ignition Deployment

# Deploy single module with verification
npm run deploy ignition/modules/MODULE --network citrea --verify --deployment-id MODULE_ID_01

# Deploy all modules
npm run deploy -- --network citrea --verify

Output:

• ignition/deployments/[deployment]/deployed_addresses.json
• ignition/deployments/[deployment]/journal.jsonl
• ignition/constructor-args/*.js

Manual Verification

npx hardhat verify --network citrea \
  --constructor-args ./ignition/constructor-args/$FILE.js \
  $ADDRESS

# Verify unrelated contracts
npx hardhat ignition verify $DEPLOYMENT --include-unrelated-contracts

NPM Package

Package Info

• Name: @juicedollar/jusd
• Version: 1.0.0 (see package.json)
• Registry: https://registry.npmjs.org

First-Time Publish

# 1. Login to NPM
npm login

# 2. Publish (build happens automatically via prepublishOnly)
yarn run publish

Publishing Updates

# 1. Update contracts (if changed)
# Edit contracts, then export ABIs:
yarn run ts:export:abis

# 2. Update version in package.json (semantic versioning)
# Patch: 1.0.0 → 1.0.1 (bug fixes)
# Minor: 1.0.0 → 1.1.0 (new features)
# Major: 1.0.0 → 2.0.0 (breaking changes)

# 3. Commit changes
git add . && git commit -m "Release v1.0.1: Description"

# 4. Publish (build happens automatically)
yarn run publish

Note: The prepublishOnly script automatically runs yarn run build before publishing.

Package Exports

TypeScript ABIs (exports/abis/):

export const JuiceDollarABI = [...] as const;

Address Config (exports/address.config.ts):

export const ADDRESS: Record<number, ChainAddress> = {
  [citrea.id]: { juiceDollar: '0x...', equity: '0x...' }
};

Foundry Fuzzing Tests

Overview

Invariant/stateful fuzzing tests verify system integrity under random operations.

Location: foundry-test/invariant/

• Invariants.t.sol - Defines system invariants
• Handler.t.sol - Defines random actions

Configuration: foundry.toml Remappings: remappings.txt

Setup

# Install Foundry: https://book.getfoundry.sh/
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Install dependencies
forge install

Run Fuzzing Tests

# Clean artifacts
forge clean

# Run tests
forge test

# Verbose output (filter noise)
forge test -vvv | grep -v "Bound result"

# Show progress
forge test --show-progress

# Re-run failed test (enable snapshots in foundry.toml)
forge test --rerun

Debug Handler Reverts

Set in foundry.toml:

[invariant]
fail_on_revert = true

License

MIT License - See LICENSE file

Copyright (c) 2024 DistributedCollective

Contributing

This project is a fork of d-EURO, which itself is a fork of Frankencoin-ZCHF.

For contribution guidelines, please open an issue in this repository or refer to the upstream dEURO repository.

Built with ❤️ by the JuiceDollar team