Skip to content

docs: remove active SUSD/StartUSD references, mark as historical #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TaprootFreak merged 1 commit into from
Apr 10, 2026
Merged

docs: remove active SUSD/StartUSD references, mark as historical #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 1 addition & 11 deletions src/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,18 +65,8 @@ JUSD can also be minted 1:1 against trusted external stablecoins through [bridge
| **USDC** | [`0x920DB0aDf6fEe2D69401e9f68D60319177dCa20F`](https://citreascan.com/address/0x920DB0aDf6fEe2D69401e9f68D60319177dCa20F) |
| **USDT** | [`0x5CC0e668F8BA61E111B6168E19d17d3C65040614`](https://citreascan.com/address/0x5CC0e668F8BA61E111B6168E19d17d3C65040614) |
| **CTUSD** | [`0x8D11020286aF9ecf7E5D7bD79699c391b224a0bd`](https://citreascan.com/address/0x8D11020286aF9ecf7E5D7bD79699c391b224a0bd) |
| **StartUSD** | [`0x51ff8141D731676Fb21aE1E5D5A88c04511994dD`](https://citreascan.com/address/0x51ff8141D731676Fb21aE1E5D5A88c04511994dD) |

Bridge volume is limited and time-restricted to minimize risk from external stablecoin failures.

### Bootstrap Phase (Temporary)

::: warning
During the initial 6-week bootstrap phase, JUSD can also be minted via the StartUSD bridge. StartUSD has no intrinsic value - it exists solely to initialize the system. After 6 weeks, this bridge expires permanently and all JUSD will be backed only by real collateral and audited stablecoins.

See [StartUSD Bridge](swap.md#startusd-bridge) for full details.
:::

### The Role of JUICE

JUICE holders provide an additional safety buffer. If liquidations result in bad debt, JUICE holders absorb the loss. This makes JUICE similar to bank equity - profitable in good times, but first in line to take losses.
Expand All @@ -99,5 +89,5 @@ Anyone can mint new JuiceDollars against a collateral using the built-in borrowi

## Technical Architecture

The JuiceDollar system consists of a set of smart contracts on Citrea. The two token contracts serve as a foundation for everything else. JuiceDollar can have an arbitrary number of contracts that have the power to mint and burn JUSD. Anyone can propose new such contracts and once they passed the governance process, they can start minting and burning JuiceDollar. Today, there are two such contracts. One is a simple bridge to bootstrap JuiceDollar based on StartUSD. The other is a contract named minting hub that serves as the central point to manage all debt positions. The JUICE token has built-in governance features and holds the equity capital of the system.
The JuiceDollar system consists of a set of smart contracts on Citrea. The two token contracts serve as a foundation for everything else. JuiceDollar can have an arbitrary number of contracts that have the power to mint and burn JUSD. Anyone can propose new such contracts and once they passed the governance process, they can start minting and burning JuiceDollar. The main contracts are the stablecoin bridges that peg JUSD 1:1 to other stablecoins, and the minting hub that serves as the central point to manage all debt positions. The JUICE token has built-in governance features and holds the equity capital of the system.
<figure style="text-align: center"><img src="/assets/arch.jpeg" alt=""><figcaption><p>Technical Architecture</p></figcaption></figure>
2 changes: 1 addition & 1 deletion src/reserve.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ If the JuiceDollar system was a company, its balance sheet would roughly look as

To provide you with an intuitive understanding of the balance sheet, let us look at what happens in three example scenarios:

1. If a user sends 100 JUSD to the stablecoin bridge to swap them into StartUSD, the balance sheet items **x** and **z** are both reduced by 100 units of that currency. The other balance positions are unaffected.
1. If a user sends 100 JUSD to a stablecoin bridge to swap them into another stablecoin (e.g., USDC), the balance sheet items **x** and **z** are both reduced by 100 units of that currency. The other balance positions are unaffected.
2. If a user mints 500 JUSD against a collateral with a reserve ratio of 20% and a fee of 5%, the following will happen on the active side: **m** will increase by 500 (because that is how much they need to repay) and **r** will increase by 125 (because that is how much they put into the borrowers reserves and paid in fees). On the passive side, **z** will increase by 500 (because that is how much is being minted), **b** will increase by 100 (because that is how much the system needs to return to the user when the position is repaid), and equity **e** will increase by 25, as the fee is never returned and now belongs to the JuiceDollar system. So in this case, minting 500 JUSD counter-intuitively expands the balance sheet by more than that, namely 625 JUSD. The collateral provided by the user is outside the balance sheet and does not appear here. Even though it is locked, it still belongs to the user.
3. A position that was used to mint 5,000 JUSD is successfully challenged, with the highest bid being 4,500 JUSD. To be able to repay everything, the system will take 600 JUSD out of the reserve, decreasing **r** by 600. Out of the 5,100 JUSD we get as a result, 5,000 JUSD are used to repay the loan, reducing both **m** and **z** by 5,000 each. The remaining 100 JUSD are sent to the challenger as a reward. Assuming that the borrower's reserve attributable to that position was 1,000 JUSD, there are 400 JUSD remaining that can be reassigned from **b** to equity **e** on the passive side. These 400 JUSD are the liquidation profits the system made in this example.

Expand Down
52 changes: 13 additions & 39 deletions src/smart-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The contracts are organized into five main categories:
| **Core** | Token contracts and reserve management |
| **MintingHub** | Position management and collateralized minting |
| **Savings** | Interest-bearing savings functionality |
| **Bridges** | Stablecoin conversion and bootstrapping |
| **Bridges** | Stablecoin conversion |
| **Gateways** | Frontend rewards and enhanced functionality |

---
Expand Down Expand Up @@ -296,14 +296,7 @@ Enables 1:1 conversion between trusted external stablecoins and JUSD.
|----------|-------|
| **Emergency Quorum** | 10% |

**StartUSD Bridge:**

| Network | Address |
|---------|---------|
| **Mainnet** | [`0x51ff8141D731676Fb21aE1E5D5A88c04511994dD`](https://citreascan.com/address/0x51ff8141D731676Fb21aE1E5D5A88c04511994dD) |
| **Testnet** | [`0x9ba2264bE7695044f59B9ca863E69aC38B3c913d`](https://testnet.citreascan.com/address/0x9ba2264bE7695044f59B9ca863E69aC38B3c913d) |

**Additional Mainnet Bridges:**
**Mainnet Bridges:**

| Bridge | Address |
|--------|---------|
Expand All @@ -313,36 +306,18 @@ Enables 1:1 conversion between trusted external stablecoins and JUSD.

---

### StartUSD
### StartUSD (Historical)

Genesis token used to bootstrap the JuiceDollar protocol during the initial 6-week launch phase.
StartUSD (SUSD) was a simple ERC-20 bootstrap token used to initialize the JuiceDollar system during a time-limited 6-week launch phase. The StartUSD bridge has since expired and SUSD is no longer part of the system.

::: warning BOOTSTRAP TOKEN
**StartUSD has no intrinsic value.** It exists solely to initialize the system during the 6-week bootstrap phase. After this period, the StartUSD bridge expires and no new SUSD can enter the system.

See [StartUSD Bridge](swap.md#startusd-bridge) for full details on the bootstrap phase and associated risks.
:::

**Key Features:**
- Simple ERC-20 token with fixed supply
- Mints 100,000,000 SUSD to deployer
- Used to initialize JUSD through the StablecoinBridge
- Creates initial JUICE token supply
- **Bridge expires after 6 weeks** - deployer influence is time-limited

| Property | Value |
|----------|-------|
| **Symbol** | SUSD |
| **Total Supply** | 100,000,000 |
| **Intrinsic Value** | None (bootstrap only) |
| **Bridge Horizon** | 6 weeks |

| Network | Address |
|---------|---------|
| **Mainnet** | [`0xD41ab73aF9c7324b9c7c6e63dE1aeC666d98bc80`](https://citreascan.com/address/0xD41ab73aF9c7324b9c7c6e63dE1aeC666d98bc80) |
| **Testnet** | [`0x8398Da4c32eaE51B9840DA230095BB29F4179590`](https://testnet.citreascan.com/address/0x8398Da4c32eaE51B9840DA230095BB29F4179590) |
| Network | Contract | Address |
|---------|----------|---------|
| **Mainnet** | Token | [`0xD41ab73aF9c7324b9c7c6e63dE1aeC666d98bc80`](https://citreascan.com/address/0xD41ab73aF9c7324b9c7c6e63dE1aeC666d98bc80) |
| **Mainnet** | Bridge (expired) | [`0x51ff8141D731676Fb21aE1E5D5A88c04511994dD`](https://citreascan.com/address/0x51ff8141D731676Fb21aE1E5D5A88c04511994dD) |
| **Testnet** | Token | [`0x8398Da4c32eaE51B9840DA230095BB29F4179590`](https://testnet.citreascan.com/address/0x8398Da4c32eaE51B9840DA230095BB29F4179590) |
| **Testnet** | Bridge (expired) | [`0x9ba2264bE7695044f59B9ca863E69aC38B3c913d`](https://testnet.citreascan.com/address/0x9ba2264bE7695044f59B9ca863E69aC38B3c913d) |

**Additional Mainnet Stablecoins:**
**Mainnet Stablecoins:**

| Token | Address |
|-------|---------|
Expand Down Expand Up @@ -441,7 +416,6 @@ Extended Savings module with frontend reward integration.
| SavingsGateway | [`0x22FE...60b`](https://citreascan.com/address/0x22FE239892eBC8805DA8f05eD3bc6aF75332b60b) | Savings with frontend rewards |
| SavingsVaultJUSD | [`0x1b70...97d`](https://citreascan.com/address/0x1b70ae756b1089cc5948e4f8a2AD498DF30E897d) | ERC-4626 savings vault |
| FrontendGateway | [`0x3090...B92`](https://citreascan.com/address/0x3090a89A1fF5DC99117BE655599e5491A0BaBB92) | Frontend reward system |
| StartUSD Bridge | [`0x51ff...4dD`](https://citreascan.com/address/0x51ff8141D731676Fb21aE1E5D5A88c04511994dD) | Bootstrap stablecoin bridge |
| USDC Bridge | [`0x920D...20F`](https://citreascan.com/address/0x920DB0aDf6fEe2D69401e9f68D60319177dCa20F) | USDC stablecoin bridge |
| USDT Bridge | [`0x5CC0...614`](https://citreascan.com/address/0x5CC0e668F8BA61E111B6168E19d17d3C65040614) | USDT stablecoin bridge |
| CTUSD Bridge | [`0x8D11...0bd`](https://citreascan.com/address/0x8D11020286aF9ecf7E5D7bD79699c391b224a0bd) | CTUSD stablecoin bridge |
Expand All @@ -458,8 +432,8 @@ Extended Savings module with frontend reward integration.
| SavingsGateway | [`0x5443...D8e`](https://testnet.citreascan.com/address/0x54430781b33581CE2b0DBD837CA66113BeEEFD8e) | Savings with frontend rewards |
| SavingsVaultJUSD | [`0x802a...c7B`](https://testnet.citreascan.com/address/0x802a29bD29f02c8C477Af5362f9ba88FAe39Cc7B) | ERC-4626 savings vault |
| FrontendGateway | [`0xd824...1D0`](https://testnet.citreascan.com/address/0xd824b7d36594Fc3088B1D91a79F34931AA2a15D0) | Frontend reward system |
| StartUSD Bridge | [`0x9ba2...3d`](https://testnet.citreascan.com/address/0x9ba2264bE7695044f59B9ca863E69aC38B3c913d) | Bootstrap stablecoin bridge |
| StartUSD | [`0x8398...590`](https://testnet.citreascan.com/address/0x8398Da4c32eaE51B9840DA230095BB29F4179590) | Genesis stablecoin |
| StartUSD Bridge (expired) | [`0x9ba2...3d`](https://testnet.citreascan.com/address/0x9ba2264bE7695044f59B9ca863E69aC38B3c913d) | Bootstrap stablecoin bridge (expired) |
| StartUSD | [`0x8398...590`](https://testnet.citreascan.com/address/0x8398Da4c32eaE51B9840DA230095BB29F4179590) | Bootstrap token (historical) |

---

Expand Down
4 changes: 2 additions & 2 deletions src/smart-contracts/functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -953,9 +953,9 @@ event PositionRewardAdded(bytes32 frontendCode, address position, uint256 amount

---

## StartUSD
## StartUSD (Historical)

Bootstrap stablecoin for protocol initialization.
Bootstrap stablecoin used for protocol initialization. The StartUSD bridge has since expired and SUSD is no longer actively used in the system.

### Functions

Expand Down
71 changes: 6 additions & 65 deletions src/swap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,72 +185,13 @@ Watch the balance changes to understand market dynamics:
| **Outflow** (burning) | JUSD is less attractive, possibly rates too low |
| **Balanced** | Market in equilibrium |

## StartUSD Bridge
## StartUSD Bridge (Historical)

The initial bootstrap bridge uses StartUSD, a simple ERC-20 token created specifically for JuiceDollar initialization.
During the initial launch of JuiceDollar, a bootstrap token called StartUSD (SUSD) was used to initialize the system. StartUSD was a simple ERC-20 token with no intrinsic value, created solely to enable the first JUSD minting and governance setup during a time-limited 6-week bootstrap phase.

### Important: Bootstrap Phase Transparency
The StartUSD bridge has since expired. SUSD is no longer part of the system and all JUSD in circulation is now backed by real collateral and audited stablecoins.

::: warning BOOTSTRAP PHASE
**StartUSD (SUSD) has no intrinsic value.** It is a simple ERC-20 token that mints its entire supply to the deployer. During the bootstrap phase, JUSD minted via the StartUSD bridge is technically **not backed by real assets**.

This is a deliberate design choice with built-in safeguards explained below.
:::

### Purpose

StartUSD serves as the genesis mechanism to:
1. Create initial JUSD supply for system testing
2. Enable first JUICE minting and governance setup
3. Bootstrap the system in a controlled environment before connecting to established stablecoins

### The 6-Week Bootstrap Window

The StartUSD bridge has a **strict 6-week horizon**. This time-limited window is a critical security feature:

| Phase | Duration | What Happens |
|-------|----------|--------------|
| **Bootstrap Phase** | Weeks 1-6 | SUSD can be bridged to JUSD, system is initializing |
| **Post-Bootstrap** | After Week 6 | SUSD bridge expires, no new SUSD can enter the system |

**After the 6-week horizon:**
- No new StartUSD can be minted into JUSD
- The deployer's ability to add unbacked JUSD is permanently removed
- Only bridges to real, audited stablecoins (USDC, USDT, etc.) remain active
- The system transitions to being fully backed by real assets

### Why This Design?

The 6-week bootstrap phase provides:

1. **Controlled Launch:** Time to identify and fix critical bugs before real capital enters
2. **Emergency Shutdown Option:** If a severe vulnerability is discovered, the system can be safely wound down
3. **Gradual Ramp-Up:** Real stablecoin bridges can be added and tested alongside the bootstrap
4. **Transparent Risk Window:** Users know exactly when the bootstrap phase ends

### Risks During Bootstrap Phase

::: danger BOOTSTRAP RISKS
During the first 6 weeks, be aware:

- **No Real Backing:** JUSD minted via SUSD is not backed by real dollar assets
- **Deployer Trust:** The deployer team could theoretically harm the system during this window

**After the 6-week horizon expires, these risks are eliminated.**
:::

### StartUSD Properties

| Property | Value |
|----------|-------|
| Name | StartUSD |
| Symbol | SUSD |
| Decimals | 18 |
| Total Supply | 100,000,000 |
| Initial Holder | Deployer |
| **Intrinsic Value** | **None** (bootstrap token only) |

### Bridge Details
### Bridge Contracts (Expired)

| Network | Address |
|---------|---------|
Expand Down Expand Up @@ -338,15 +279,15 @@ event EmergencyStopped(address indexed caller, string message)

| Bridge | Source | Address | Status |
|--------|--------|---------|--------|
| StartUSD | SUSD | [`0x51ff...4dD`](https://citreascan.com/address/0x51ff8141D731676Fb21aE1E5D5A88c04511994dD) | Active |
| USDC | USDC | [`0x920D...20F`](https://citreascan.com/address/0x920DB0aDf6fEe2D69401e9f68D60319177dCa20F) | Active |
| USDT | USDT | [`0x5CC0...614`](https://citreascan.com/address/0x5CC0e668F8BA61E111B6168E19d17d3C65040614) | Active |
| CTUSD | CTUSD | [`0x8D11...0bd`](https://citreascan.com/address/0x8D11020286aF9ecf7E5D7bD79699c391b224a0bd) | Active |
| StartUSD | SUSD | [`0x51ff...4dD`](https://citreascan.com/address/0x51ff8141D731676Fb21aE1E5D5A88c04511994dD) | Expired |

### Testnet (Chain ID: 5115)

| Bridge | Source | Address | Status |
|--------|--------|---------|--------|
| StartUSD | SUSD | [`0x9ba2...3d`](https://testnet.citreascan.com/address/0x9ba2264bE7695044f59B9ca863E69aC38B3c913d) | Active |
| StartUSD | SUSD | [`0x9ba2...3d`](https://testnet.citreascan.com/address/0x9ba2264bE7695044f59B9ca863E69aC38B3c913d) | Expired |

*Additional bridges may be added through governance.*