@deuro/eurocoin

dEURO

This repository is a friendly fork of Frankencoin-ZCHF.

This is the source code repository for the smart contracts of the oracle-free, collateralized stablecoin dEURO.

There also is a public frontend and a documentation page.

Source Code

The source code can be found in the contracts folder. The following are the most important contracts.

Contract	Description
DecentralizedEURO.sol	The DecentralizedEURO (dEURO) ERC20 token
Equity.sol	The Native Decentralized Euro Protocol Share (nDEPS) ERC20 token
MintingHub.sol	Plugin for oracle-free collateralized minting
Position.sol	A borrowed minting position holding collateral
PositionRoller.sol	A module to roll positions into new ones
StablecoinBridge.sol	Plugin for 1:1 swaps with other EUR stablecoins
BridgedToken.sol	Generic bridged token contract for L2 deployments, e.g. dEURO on Optimism & Base, DEPS on Base
Savings.sol	A module to pay out interest to ZCHF holders
Leadrate.sol	A module that can provide a leading interest rate for the system
PositionFactory.sol	Create a completely new position in a newly deployed contract
DEPSWrapper.sol	Enables nDEPS to be wrapped in DEPS
FrontendGateway.sol	A module that rewards frontend providers for referrals into the dEURO Ecosystem
MintingHubGateway.sol	Plugin for oracle-free collateralized minting with rewards for frontend providers
SavingsGateway.sol	A module to pay out interest to ZCHF holders and reward frontend providers
SavingsVaultDEURO.sol	ERC-4626 vault wrapper for the Savings module

Code basis and changes after the fork

The last status adopted by Frankencoin was Commit a2ce625c554bbd3465a31e7d8b7360a054339dd2 on December 2, 2024. The following things were built on it as a fork.

DecentralizedEURO Core module

• ZCHF was renamed to dEURO
• Frankencoin was renamed to DecentralizedEURO
• FPS was renamed to nDEPS (native Decentralized Protocol Share)
• nDEPS now cost 10_000 times less than the FPS for Frankencoin
• In the Equity SmartContract, the valuation factor was adjusted from 3 to 5.
• ERC20 token has been completely converted to standard Open Zeppelin V5
• ERC165 token standard has been added
• ERC3009 added
• SmartContract internal exchange fee (can also be called issuance fee) increased from 0.3% to 2%
• Minters are no longer authorized to execute SendFrom and BurnFrom from any address. https://github.com/d-EURO/smartContracts/pull/108

Savings

The lock-up of 3 days has been removed without replacement.

DEPS Wrapper

• FPS has been renamed to nDEPS
• WFPS has been renamed DEPS
  (so “w” is no longer used for “wrapped” but the non-wrapped version is now called “native”)

Bridges

Frankencoin had a single bridge to XCHF from Bitcoin Suisse
dEURO has 4 bridges to

• Tether EUR
• Circle EUR
• VNX EUR
• Stasis EUR
  The new tokens in the bridges have different decimal places.

Minting module v1

In contrast to Frankencoin, dEURO does not use the minting module v1 at all

Minting module v2

Interest is no longer paid when a position is opened but is credited as a debt on an ongoing basis and only has to be paid when a position is closed or modified.

Minting module v3

Native ETH/WETH support across MintingHub, Position, and PositionRoller. Leadrate integrated directly into MintingHub. Interest is now charged only on the usable mint (excluding reserve contribution). A reference position mechanism allows cooldown-free price increases.

Front-end gateway

It is possible to use the SmartContracts through a gateway and thus obtain a refferal commission. This module is completely new.

Audit Reports

2023-02-10 Blockbite
2023-06-09 code4rena
2023-10-30 chainsecurity Report 1
2024-09-25 Decurity
2024-11-28 ChainSecurity Report 2

Development

Yarn Package Scripts

// yarn run <command> args...

"wallet": "npx ts-node helper/wallet.info.ts",

"compile": "npx hardhat compile",
"test": "npx hardhat test",
"coverage": "npx hardhat coverage",

"deploy": "npx hardhat run scripts/deployment/deploy/<script>.ts --network <network>",
"verify": "npx hardhat verify",

"build": "tsup",
"publish": "npm publish --access public"

1. Install dependencies

yarn install

2. Set Environment

See .env.example

file: .env

ALCHEMY_RPC_KEY=...
DEPLOYER_SEED="test test test test test test test test test test test junk"
DEPLOYER_SEED_INDEX=1 // optional, select deployer
DEPLOYER_PRIVATE_KEY=... // optional, replaces deployer seed
ETHERSCAN_API_KEY=...
USE_FORK=false
CONFIRM_DEPLOYMENT=false

Create new session or re-navigate to the current directory, to make sure environment is loaded from .env

3. Develop Smart Contracts

Develop your contracts in the /contracts directory and compile with:

yarn run compile					# Compiles all contracts

4. Testing

All test files are located in /test directory. Run tests using:

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

With tsc-watch (auto refresh commands)

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

5.0 Deploy Contract (manual)

Then run a deployment script with tags and network params (e.g., sepolia that specifies the network)

hh deploy --network sepolia --tags MockTokens
hh deploy --network sepolia --tags DecentralizedEURO
hh deploy --network sepolia --tags PositionFactory
hh deploy --network sepolia --tags MintingHub
hh deploy --network sepolia --tags MockEURToken
hh deploy --network sepolia --tags XEURBridge
hh deploy --network sepolia --tags positions

Recommanded commands for sepolia network. Test deployments on a local Mainnet fork using npx hardhat node with USE_FORK=true in .env. The networks are configured in hardhat.config.ts, including the Mainnet fork. Set CONFIRM_DEPLOYMENT=true to enable confirmation prompts before each deployment.

Deploy Stablecoin Bridges

Deploy bridges for EUR stablecoins using the dedicated deployment script:

# Deploy bridge for specific stablecoin, e.g. EUROP
BRIDGE_KEY=EUROP npx hardhat run scripts/deployment/deploy/deployBridge.ts --network mainnet

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

Bridge keys and configurations are defined in scripts/deployment/config/stablecoinBridgeConfig.ts

5.1 Manual Verify

npx hardhat verify --network polygon --constructor-args $CONSTRUCTOR_ARGS_FILE $ADDRESS

6 Prepare NPM Package Support

• Export ready to use TypeScript ABIs
• Export ready to use TypeScript deployed address config
• ...

6.1 TypeScript ABIs

Export contract ABIs for npm package usage by copying the JSON into dedicated TypeScript files:

file: exports/abis/...

export const StorageABI = [
...
JSON
...
] as const;

6.2 TypeScript Address Config

Provides a mapping of contract addresses for the Membership and Storage contracts deployed on different blockchain networks.

The ADDRESS object contains the contract addresses for the mainnet and polygon networks, with the network ID as the key. The zeroAddress is used as a placeholder for the mainnet network, as the contracts have not been deployed there yet.

file: exports/address.config.ts

import { mainnet, polygon } from 'viem/chains';
import { Address, zeroAddress } from 'viem';

export interface ChainAddress {
	membership: Address;
	storage: Address;
}

export const ADDRESS: Record<number, ChainAddress> = {
	[mainnet.id]: {
		membership: zeroAddress, // if not available
		storage: zeroAddress,
	},
	[polygon.id]: {
		membership: '0x72950A0A9689fCA941Ddc9E1a58dcD3fb792E3D2',
		storage: '0x8A7e8091e71cCB7D1EbDd773C26AD82AAd323328',
	},
};

7. TSUP and npm package

7.1 TSUP

Config: /tsup.config.ts

TSUP bundles TypeScript code into optimized JavaScript packages. This package uses TSUP to create production-ready builds.

yarn run build

7.2 NPM Package

Increase Version: Update version number in package.json using semantic versioning (e.g. 0.0.1 -> 0.0.2) before publishing new changes.

file: /package.json

"name": "@frankencoin/zchf",
"version": "0.2.16", <-- HERE

Login to your NPM account

npm login

This will publish your package to NPM with public access, making it available for anyone to install and use.

yarn run publish

To publish new version. publish: "npm publish --access public"

Note: During npm package publishing, the command may execute twice. The second execution will fail with a version conflict since the package is already published. This is expected behavior and the first publish will have succeeded.

7.3 How to transpile package into bundled apps

(not needed, since its already a true JS bundled module)

E.g. for NextJs using the next.config.js in root of project.

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  transpilePackages: ["@.../core", "@.../api"],
};

module.exports = nextConfig;

8. Updates (January 2025)

DecentralizedEURO.sol

• allowance: Added address(reserve)) to the spender addresses with unlimited dEURO allowance.
• burnWithReserve: Removed unused function.
• burnFromWithReserve: Use _spendAllowance to control spending power of minters based on allowance.
• burnFromWithReserveNet: Renamed from burnWithReserve.
• distributeProfits: New function to distinguish between reserve withdrawals due to losses vs interest payouts (e.g. to savings) -> Loss vs ProfitDistributed event.
• _withdrawFromReserve: New helper function used by coverLoss and distributeProfits.
• supportsInterface: Added IDecentralizedEURO support.

Equity.sol

• BelowMinimumHoldingPeriod: New custom error for failed !canRedeem(owner) check.

MintingHub.sol

• _finishChallenge: The Position.notifyChallengeSucceeded call now returns both the required principal repayment amount and interest payment amount. The bidder pays only the offer (unit price × collateral): DEURO.transferFrom(msg.sender, address(this), offer). After deducting the challenger reward, the remaining funds cover both repayment and interest from the same pool. If fundsAvailable > repayment + interest, the surplus is split between reserve profits and the position owner. If insufficient, coverLoss draws from the reserve. Interest is collected at the end via DEURO.collectProfits(address(this), interest).
• buyExpiredCollateral: The buyer pays forceSalePrice * amount. The proceeds are passed to Position.forceSale(buyer, amount, proceeds) which handles interest repayment and principal repayment from the same pool internally.

Position.sol

• fixedAnnualRatePPM: The interest rate for a position is synced with the lead rate (Leadrate.currentRatePPM) at creation time (in the constructor or, in the case of cloning, in the initialize function) using the _fixRateToLeadrate function. From this point onwards, the interest rate for a particular position instance is fixed unless new tokens are minted (the loan is increased), at which point it is re-synced with the lead rate. It is expected that in the case of lowered interest rates, position owners will roll their current positions into new ones (for free) to benefit from it.
• availableForClones: This function now only considers the principal amount in its calculations. This is because the (accrued) interest does not belong to the minted dEURO tokens of a position and therefore do not belong in this calculation.
• adjust: The newDebt parameter was changed to newPrincipal. Consequently, owners are able to control their principal amount without having the outstanding interest amount tied to it. Naturally, if they wish to reduce their principal, they must first pay any outstanding interest. This is handled automatically by the adjust function.
• MintingUpdate: The last paramter of this event now only reports the new principal amount and not the entire debt amount which would include the outstanding interest. This is more in line with the overall purpose of this event.
• _adjustPrice: The accrued interest is removed from the bounds paramter passed to _setPrice. This is because the interest does not belong in the collateral "sanity check" logic.
• _accrueInterest: Refactored
• _calculateInterest: Renamed and refactored from getDebtAtTime.
• getDebt: Refactored
• getInterest: New public function to get the currently outstanding (unpaid) interest on the position.
• _mint: Updated to manage interest accrual and the syncing of the interest rate to the lead rate.
• _notifyRepaid: Refactored, including sanity check.
• _notifyInterestPaid: Refactored, including sanity check.
• forceSale: The function signature is forceSale(address buyer, uint256 colAmount, uint256 proceeds). Interest repayment and principal repayment are handled from the proceeds pool. Interest is repaid first, then the principal is repaid using _repayPrincipalNet. If proceeds exceed what's needed, the surplus goes to the position owner. If no collateral remains after the sale, any outstanding principal is covered by the system via coverLoss.
• _payDownDebt: Refactored
• _repayInterest: New helper function to pay off outstanding interest by some amount. Returns the remainder in the case that amount exceeds the outstanding interest.
• _repayPrincipal: New helper function to repay principal by some exact amount using burnFromWithReserve. Returns the remaining funds.
• _repayPrincipalNet: New function to repay principal by some amount, where amount specifies the amount to be burned from the payer. This is done using the DecentralizedEURO.burnFromWithReserveNet function. As _repayPrincipalNet is used by the forceSale function, repayPrincipalNet(buyer, proceeds);, where proceeds may exceed getUsableMint(principal) amount (the maximum amount claimable by a particular position) we cap repayWithReserve at said maximal claimable amount. If funds remain thereafter, they are burned directly in order to pay of any remaining principal. The final remainder is returned.
• notifyChallengeSucceeded: Now computes and returns the proportional amount of interest that must be paid in order to successfully challenge a position.

PositionRoller.sol

• rollFullyWithExpiration: Fix logic to compute the amount to mint in the target Position.
• roll: Refactor and send any remaining flash loan from the debt repayment (reserve portion returned by source.repay(totRepayment) > Position._repayPrincipal > DecentralizedEURO.burnFromWithReserve) to msg.sender for the flash loan repayment.
• _cloneTargetPosition: New helper function used to clone the target position. Used only by PositionRoller.roll.

Savings.sol

• refresh: Replace the use of DecentralizedEURO.coverLoss with DecentralizedEURO.distributeProfits. This replaces the Loss event with the ProfitDistributed event.

StablecoinBridge.sol

• mintTo: Replace standard transfer functions with OppenZeppelin's SafeERC20 variants for the source stablecoin.

Gateway Contracts

The gateway contracts (FrontendGateway.sol, SavingsGateway.sol, MintingHubGateway.sol) provide a way to generously reward frontend providers or referrer, paid for by DEPS Holder. These Contracts are not present in the Frankencoin Ecosystem.

Invariant/Stateful Fuzzing Tests with Foundry:

The fuzzing tests are written in Solidity and made of two main contracts located in the foundry-test/invariant folder: Invariants.t.sol which contains the invariants and Handler.t.sol which contains the actions of the fuzzing test. During each run the functions in Handler.t.sol are called by the fuzzing engine in a random order and with random inputs starting with the initial state of the system as defined by Invariants.setUp(). After each run the invariants defined in Invariants.t.sol are checked to ensure that the system is still in a valid state.

Running the Fuzzing Tests:

After installing foundry on your machine and running forge install to install the required dependencies, you can use the following command to run the fuzzing tests:

# remove build artifacts & cache
forge clean

# run the fuzzing tests
forge test

# more verbose output (with grep to omit some logs)
forge test -vvv | grep -v "Bound result"

# show progress
forge test --show-progress

# re-run a failed test
# Tip: Set .profile.logging.snapshot=true in foundry.toml to log snapshots
forge test --rerun

The configuration for the fuzzing tests can be found in the foundry.toml file. Furthermore, the remappings.txt file contains the remappings for the fuzzing test contracts. In order to debug handler reverts, you can set .invariant.fail_on_revert=true in the foundry.toml file.