@juicedollar/jusd

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

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