# Introduction

**Curated yield from real-world regenerative lending.**

Regenerative.fi exists to accelerate Regenerative Finance (ReFi). Our single product — **USDREFI** — is the simplest, real way to generate yield while funding regenerative impact.

Deposit stablecoins. Earn yield. Help the world. That's it.

***

### What is Regenerative Finance?

Regenerative Finance (ReFi) integrates financial practices with social responsibility, sustainability, and ecological regeneration. Rather than extracting value, ReFi creates economic systems that restore and enhance social, environmental, and economic well-being.

### One Product. One Mission.

USDREFI is a regenerative yield dollar — a stablecoin-denominated savings product where your yield comes exclusively from curated, real-world regenerative lending. Every dollar deposited is deployed into lending that is financially sound, socially just, and ecologically safe, verified through our [Credit Curation Framework](/credit-curation/methodology).

### Built on Celo

USDREFI is deployed on [Celo](https://celo.org/), the leading blockchain network for regenerative development. The Regenerative dApp is open-source and operates as a Public Good on Celo.

### Explore

* **App:** [app.regenerative.fi](https://app.regenerative.fi/)
* **Website:** [regenerative.fi](https://www.regenerative.fi/)
* **Twitter:** [@RegenerativeFi](https://twitter.com/RegenerativeFi)
* **Mirror:** [mirror.xyz/regenerativefi.eth](https://mirror.xyz/regenerativefi.eth)


# What is USDREFI

USDREFI is a liquid, transferable, regenerative savings product built on Celo. At a high level:

* **Stablecoin in** — deposit USDC into the vault
* **Productive deployment underneath** — capital is deployed into curated real-world regenerative lending
* **Liquid on-chain token on top** — receive USDREFI tokens representing your position

Users deposit stablecoins and receive USDREFI, representing a position in a vault that deploys capital into regenerative credit opportunities. Yield is generated from real-world lending to smallholder farmers, cooperatives, and micro-entrepreneurs who meet our curation standards. The vault handles all deployment, claiming, and reinvestment on behalf of users.

## The Gap in the Market

USDGLO and similar "for-good" stablecoins are inactive or have failed to scale. Stablecoin holders currently have no simple way to generate yield from regenerative sources. Existing ReFi lending products require active management, long lock-ups, and hands-on reinvestment. Meanwhile, demand for purpose-aligned on-chain yield is growing — but the options barely exist.

USDREFI fills that gap.

## What USDREFI Is Not

* **Not a risk-free stablecoin** or capital-guaranteed product
* **Not a maximum-yield optimizer** — yield comes from real lending, not leverage
* **Not a wrapped DeFi position** or leverage play
* **Not uncurated** — every yield source passes through the Credit Curation Framework

## Who It's For

**For stablecoin holders:** Higher total return than parking capital in standard savings, backed by real-world productive activity with clear regenerative alignment.

**For ReFi participants:** Much more liquid than direct lending, no manual claiming or reinvestment, simpler UX, and lower operational burden.

**For the world:** Passive stablecoin capital is channeled into real-world regenerative lending — an on-ramp from idle capital to measurable impact.


# How it works

USDREFI is designed to be a set-and-forget regenerative savings experience. Here's the complete flow.

## Deposit

1. Verify your identity via [Self](/architecture/identity-and-tiers) to unlock vault access
2. Approve USDC spend and deposit into the USDREFI vault
3. Receive USDREFI tokens at a 1:1 rate representing your position
4. The Foundation Safe deploys your capital into curated regenerative credit positions

The vault enforces per-user caps based on your identity tier, and a global cap to manage total exposure.

## Earn Yield

Your deposited capital is deployed into curated lending sources — starting with Quipu (Colombian AI-powered microcredit) via Textile infrastructure. Yield from these real-world loans flows back to the protocol monthly.

Rewards are distributed through [Merkl](/architecture/rewards) as a combination of USDREFI and $REFI tokens. You claim rewards on-demand via on-chain Merkle proofs, or compound by re-depositing claimed USDREFI back into the vault.

## Exit

USDREFI does not support direct vault withdrawals. To exit, you swap USDREFI for USDC on the [Uniswap V4 USDREFI/USDC pool](/architecture/uniswap-pool).

USDREFI is designed to trade close to $1 but is not a hard-pegged stablecoin — the swap is a market transaction. Protocol-owned liquidity and LP incentives maintain pool depth for healthy exits.

{% hint style="info" %}
If the Uniswap pool ever loses critical liquidity, the Foundation Safe can enable emergency direct vault withdrawals as a safety measure.
{% endhint %}

## The USDREFI Flywheel

USDREFI creates a self-reinforcing regenerative cycle:

1. **Deposits** flow through the Credit Curation Framework into curated lending sources
2. **Yield** is generated from real-world regenerative loans
3. **Yield splits three ways** — to users (rewards), to the protocol (liquidity & operations), and to $REFI incentives
4. **All three streams converge** back into regeneration: users re-deposit and compound, the protocol deepens liquidity and funds new sources, and incentives attract new participants

Every dollar of yield strengthens the system's capacity to regenerate.


# Know Risks

USDREFI is transparent about its risks. It is not a risk-free product and is not designed to be fully trustless — it is designed to be transparent and accountable.

## Key Risks

**Liquidity risk:** Exiting USDREFI depends on Uniswap pool depth. In stressed conditions, you may experience slippage or be unable to swap the full amount at \~$1. The Foundation Safe can enable emergency direct vault withdrawals if the pool loses critical liquidity.

**Credit risk:** The underlying yield comes from real-world loans. Borrowers may default, which would reduce effective yield. The Credit Curation Framework mitigates this through structured evaluation, but it cannot eliminate default risk.

**Operational risk:** Users rely on multisig operators (Foundation Safe) and the governance process to act competently. Capital deployment, yield collection, and reward distribution are currently manual processes.

**Price risk:** USDREFI is designed to trade near $1 but is not a hard-pegged stablecoin. It may trade at a premium or discount depending on market conditions and pool liquidity.

**Reward risk:** Reward rates are set by the Foundation and are not guaranteed. They may change based on yield from underlying sources.

## Trust Assumptions

Using USDREFI means trusting:

* **The curated originators** — that they are lending responsibly and generating real yield
* **The vault operators** — that the Foundation Safe multisig deploys and manages capital correctly
* **The governance process** — that the Credit Curation Framework is applied honestly and rigorously
* **The identity system** — that tier assignment and access control function as described

The Credit Curation Framework is what earns and maintains that trust through structured, repeatable evaluation. All positions are reviewed annually, with triggered re-evaluations for material changes.

## Mint Caps as Risk Management

Mint caps are a core risk tool:

* **Global cap** limits total TVL exposure
* **Per-user caps** (by tier) reduce concentration risk
* Caps are raised gradually as liquidity depth and operational confidence increase


# Yield and Economics

All USDREFI yield comes from real-world regenerative lending. There is no leverage, no DeFi composability risk, and no synthetic yield.

## Yield Sources

### Quipu via Textile (v1 — Launch)

The initial yield source is Quipu, a Colombian AI-powered microcredit originator that has disbursed over 49,400 loans using 80,000+ alternative data points. Capital is deployed through Textile's smart contract infrastructure.

### EthicHub (v1 — Phase 2)

EthicHub provides long-duration loans (12–24 months) to smallholder farmers and cooperatives. It generates USD-denominated yield plus upside from EthicHub's ETHIX ecosystem token. EthicHub has an established track record and meets the Credit Curation Framework standards.

### Expansion

As new originators pass through the [Credit Curation Framework](file:///2028660/framework/overview.md), the USDREFI basket will diversify into regenerative agriculture, renewable energy, micro-enterprise, and similar sectors. Every addition must clear all five gates.

## Yield Economics

| Metric                       | Value                                             |
| ---------------------------- | ------------------------------------------------- |
| EthicHub Gross Yield (12-mo) | \~10% (8% USD + \~2% ETHIX)                       |
| EthicHub Gross Yield (24-mo) | \~13% (8% USD + \~5% ETHIX)                       |
| User Yield Target            | \~4% APY in USD (comparable to sDAI/Spark)        |
| Surplus                      | Retained to build protocol-owned liquidity        |
| Ops & Infra                  | \~$20–25k/year (lean human ops + minimal tooling) |

## How Yield Reaches You

Yield does **not** accrue into the USDREFI share price (the exchange rate stays 1:1). Instead, rewards are distributed as a side-stream via Merkl campaigns:

1. Curated lending sources generate yield monthly
2. The Foundation Safe receives yield and transfers the reward portion to the Reward Safe
3. The Reward Safe funds a Merkl campaign with USDREFI + $REFI tokens
4. Merkl snapshots holder balances and builds a Merkle tree
5. You claim your pro-rata share on-demand via on-chain proof

This design keeps the vault simple and ERC-4626 compliant while providing transparent, claimable rewards.


# Roadmap

USDREFI launches in March 2026 with a proof-of-concept deployment, then scales through the year as curated sources are added and confidence grows.

## Phased Rollout

{% stepper %}
{% step %}

#### Phase 1: POC with Quipu via Textile (March 2026)

First live capital, first live yield. Validates the vault mechanics, curation framework in practice, and on-chain UX end-to-end.

* **Deployment:** $25k into Quipu via Textile smart contract infrastructure
* **Curated source:** Quipu — Colombian AI-powered microcredit, 49,400 loans disbursed
* **Curation score:** 45/100 (Tier 3), Bennett Average 1.83
* **Purpose:** Prove the model works with real money before scaling
  {% endstep %}

{% step %}

#### Phase 2: Add EthicHub, Scale to $100k+ (April–May 2026)

EthicHub is added as the second curated source, providing long-duration loans (12–24 months) to smallholder farmers generating \~10% gross yield. With two sources live, USDREFI becomes a genuine diversified basket.

* **Target TVL:** $100k+ across Quipu and EthicHub
* Begin onboarding trusted early holders beyond founders
* Seed protocol-owned liquidity for the Uniswap secondary market
* Raise global vault cap to $100k
* Deepen Uniswap pool liquidity
  {% endstep %}

{% step %}

#### Phase 3: Growth to $250k (June–December 2026)

Focus shifts to growing TVL through onboarding additional holders (invite-only), deepening secondary market liquidity, and evaluating new originators through the Credit Curation Framework.

* **Target TVL:** $250k by year-end
* Ongoing curation pipeline for new originators
* First monthly impact reports
  {% endstep %}

{% step %}

#### Scale Decision (Q4 2026)

At $250k TVL, begin exploring EURREFI (EUR-denominated counterpart) and/or strategies to scale USDREFI by 10x through institutional channels and additional curated sources.
{% endstep %}
{% endstepper %}


# Methodology

The Regenerative Credit Curation Framework (v1.0) is the intellectual backbone of USDREFI. It is a structured, repeatable methodology for evaluating on-chain credit originators. Every lending source that feeds USDREFI yield must pass through this framework.

This is what makes USDREFI "regenerative" — not by label, but by verified standard.

## Three Core Standards

Every originator is evaluated against three non-negotiable standards:

* **Financially Sound** — The originator operates with integrity, transparency, and sustainable credit practices. Loan structures are fair, default histories are disclosed, and on-chain verifiability is present.
* **Socially Just** — Loans reach genuinely excluded borrowers and produce measurable improvements in their lives. This means real financial inclusion, not just fintech with a green label.
* **Ecologically Safe** — Credit flows avoid planetary harm and ideally finance regeneration. Lending sectors are evaluated against ecological ceilings and resource use impacts.

## The Minimum Bar

To be included in the USDREFI basket, an originator must achieve a **Bennett Average of 1.5 or above**, placing it in the "Sustainable DeFi" classification at minimum. This means the originator demonstrates a genuine inclusion mission with real, measured outcomes.

Originators scoring below this threshold — or scoring 1 (Conventional) across all Bennett dimensions — are not eligible, regardless of their financial returns.

## Governance & Re-evaluation

All active positions are reviewed on an **annual cycle**, with triggered re-evaluations for material changes such as ownership transitions, defaults, rate changes, or new impact data.

Automatic downgrade review is triggered by:

* PAR 90 exceeding 25% for two consecutive quarters
* Unresolved defaults
* Loss of key institutional backing

New protocols must complete all gates before any allocation, with minimum documentation including audited pool data, rate disclosure, borrower profile, and originator KYB.


# Give Gate Process

Every originator passes through five sequential gates. Gates 1 and 2 are pass/fail — failure at either disqualifies entirely. Gates 3 and 4 produce numeric scores. Gate 5 is a bonus for field-building contribution.

## Gate 1 — Financial Integrity (Pass / Fail)

Evaluates whether the originator operates a sound credit business:

* Borrower transparency and loan structure quality
* Default history and disclosure
* Rate fairness
* On-chain verifiability of pool data

**Failing Gate 1 disqualifies the originator entirely.** No amount of impact can compensate for a fundamentally unsound lending operation.

## Gate 2 — Regenerative Alignment (Pass / Fail)

Assesses two dimensions:

* **Social floor:** Does lending genuinely benefit excluded borrowers and their communities?
* **Ecological ceiling:** Is the lending sector aligned with ecological safety? Does it avoid resource damage?

**Failing Gate 2 disqualifies the originator.** Profitable lending that is extractive or ecologically harmful is not eligible.

## Gate 2B — Bennett Structural Alignment (Score: 1–3)

A six-dimension evaluation that maps the originator onto a structural spectrum:

| Score | Classification       | Meaning                                           |
| ----- | -------------------- | ------------------------------------------------- |
| 1     | Conventional         | Standard fintech/DeFi with no regenerative intent |
| 2     | Sustainable DeFi     | Genuine inclusion mission with measured outcomes  |
| 3     | Regenerative Finance | Structurally transformative, systems-level impact |

The Bennett Average across all six dimensions must be **1.5 or above** to qualify for inclusion in the USDREFI basket.

## Gate 3 — Social Score (0–50 points)

Quantitative scoring across five social dimensions:

* Financial inclusion depth
* Loan fairness and terms
* Employment and livelihood impact
* Community wealth effects
* Gender equity

## Gate 4 — Ecological Score (0–50 points)

Quantitative scoring across five ecological dimensions:

* Ecological activity type
* Carbon impact
* Biodiversity effects
* Circularity practices
* Verifiability of environmental claims

## Gate 5 — Field-Building Bonus (0–20 points)

Bonus points awarded for contributions that strengthen the broader ReFi ecosystem:

* Open-source software and tooling
* Published frameworks and methodologies
* Documented pilot programs
* Openness and data sharing

## Combined Score

The **Gate 3 + Gate 4** total (0–100) plus the **Gate 5** bonus determines the originator's final score and [tier placement](broken://pages/0520fab70953c6a2e2c7ef54b60e186756378ae2).


# Tier System

The combined Gate 3 + Gate 4 score (0–100) plus Gate 5 bonus determines tier placement. Each tier carries a maximum allocation limit to ensure diversification and manage risk.

## Originator Tiers

<table><thead><tr><th>Tier</th><th>Score</th><th>Description</th><th data-hidden>Max Allocation</th></tr></thead><tbody><tr><td><strong>Tier 1</strong></td><td>80–100</td><td>Exemplary regenerative. Structurally transformative with verified impact.</td><td>Up to 30%</td></tr><tr><td><strong>Tier 2</strong></td><td>60–79</td><td>High-quality impact. Sustainable DeFi or above with strong scores.</td><td>Up to 20%</td></tr><tr><td><strong>Tier 3</strong></td><td>40–59</td><td>Watchlist / conditional. Passes gates but with improvement path needed.</td><td>Up to 10%</td></tr><tr><td><strong>Below 40</strong></td><td>—</td><td>Fails Gate 1, Gate 2, or scores below 40. Not included.</td><td>Not eligible</td></tr></tbody></table>

No single originator or protocol may exceed its tier's maximum allocation, regardless of score. This is a structural diversification rule, not a performance penalty.

## Current Originator: Quipu

Quipu is the first curated originator in the USDREFI basket:

* **Score:** 45/100 (Tier 3 — Sustainable DeFi classification)
* **Bennett Average:** 1.83 (clears the 1.5 minimum bar)
* **Profile:** Colombian AI-powered microcredit, 80,000+ alternative data points, 49,400 loans disbursed

## Diversification by Design

The allocation cap system ensures that USDREFI never becomes over-exposed to a single originator. As new originators pass through the framework and are added to the basket, concentration risk decreases naturally. The framework incentivizes seeking higher-scoring originators that unlock larger allocation caps.


# REFI Token

The Regenerative Finance Token ($REFI) is the network ownership token. It provides holders with governance over the treasury, protocol direction, and incentive allocation.

## Business Model

For each regenerative product (starting with USDREFI), revenue generated must exceed operational costs plus $REFI incentives. Margins support future regeneration per holder decisions.

## Distribution

| Allocation              | Share |
| ----------------------- | ----- |
| Treasury & Public Goods | 50%   |
| ReFi Foundation         | 15%   |
| Team & Advisors         | 15%   |
| Strategic Partners      | 15%   |
| Airdrops                | 5%    |

## Utility

**Ownership** — $REFI holders collectively own protocol-owned liquidity and the treasury.

**Priority access** — Holders get early access to regenerative-aligned products launched by the protocol.

## Role in USDREFI

$REFI plays two roles in the USDREFI system:

1. **Holder rewards** — Distributed alongside USDREFI yield via Merkl campaigns, giving depositors exposure to protocol upside
2. **LP incentives** — Distributed to Uniswap pool liquidity providers to maintain exit liquidity depth


# Goverance

USDREFI governance is designed for practical decision-making at current scale, with a clear path to progressive decentralization.

## Foundation Multisig

During the current phase, vault assets are held in **multisig-controlled Gnosis Safes** operated by the Regenerative Finance Foundation. The Foundation Safe uses a 2-of-3 threshold with clear signer roles and separation of duties.

The Foundation Safe controls:

* Capital deployment into curated credit pools
* Vault parameters (global cap, tier caps)
* TierRegistry overrides
* Emergency withdrawal toggle
* Reward distribution funding

## Legal Structure

USDREFI launches as a **non-custodial, hosted solution**. During the Beta phase:

* The Regenerative Finance Foundation hosts the interface
* The Foundation acts as counterparty to lending platforms
* Users sign Terms and Conditions via wallet on first deposit
* The Foundation is not liable for losses
* Product details may change at the Foundation's discretion

To increase deposit ceilings or introduce more complex assets, Regenerative intends to transition to a dedicated legal entity (e.g. a Curaçao BV or external regulated service provider).

## Terms & Conditions

Key terms users agree to on first deposit:

* No direct withdrawals — exit via secondary market swap only
* USDREFI may trade at discount or premium
* Reward rates are not guaranteed
* The Foundation is not liable for losses from credit defaults, market conditions, or operational issues


# System Overview

USDREFI is a tokenized vault on Celo that accepts USDC deposits and issues USDREFI receipt tokens at a fixed 1:1 rate. The underlying capital is manually deployed by the Foundation multisig Safe into curated regenerative credit pools, generating real-world yield distributed to holders through Merkl.

## Design Principles

* **Manual capital management** over automated strategy wrappers (POC simplicity)
* **Identity-gated access** via API-assigned tiers, not on-chain identity checks
* **Swap-only exit** — no direct vault withdrawals; Uniswap pool is the sole exit path
* **Separate reward streams** for holders and LPs
* **Foundation Safe retains full admin control** with emergency overrides
* **ERC-4626 compliance** for ecosystem tooling compatibility

## Component Map

| Component             | Type                      | Admin              | Status       |
| --------------------- | ------------------------- | ------------------ | ------------ |
| USDREFI Vault         | ERC-4626 (Solidity)       | Foundation Safe    | To deploy    |
| TierRegistry          | Custom mapping (Solidity) | Foundation Safe    | To deploy    |
| Foundation Safe       | Gnosis Safe 2-of-3        | Signers: M + L + 1 | To deploy    |
| Reward Safe           | Gnosis Safe 2-of-3        | Signers: M + L + 1 | To deploy    |
| Tier Assignment API   | Off-chain service         | Foundation         | To build     |
| Merkl Holder Campaign | Merkl protocol            | Reward Safe        | To configure |
| Merkl LP Campaign     | Merkl protocol            | Reward Safe        | To configure |
| Uniswap V4 Pool       | Concentrated Liquidity    | Permissionless     | To deploy    |
| Frontend App          | React / Next.js           | L                  | To build     |
| Dune Dashboard        | Dune Analytics            | M                  | To build     |

## Separation of Concerns

The system is designed around clear boundaries:

* **Vault contract** → deposits and share accounting
* **Foundation Safe** → capital allocation and governance parameters
* **Reward Safe** → funds reward distributions
* **TierRegistry** → access control
* **Merkl** → reward computation and claims
* **Uniswap pool** → secondary liquidity and exit

## POC Simplifications

Several components are intentionally deferred for the proof-of-concept. These are documented upgrade paths, not missing features:

| Removed for POC          | Replaced by                           | Upgrade path               |
| ------------------------ | ------------------------------------- | -------------------------- |
| Strategy wrapper         | Manual Safe deposits to Textile/Quipu | On-chain strategy adapter  |
| Yield router contract    | Reward Safe + Merkl campaigns         | Automated split logic      |
| Harvest keeper bot       | Monthly off-chain snapshots           | Automated harvest          |
| Direct vault withdrawals | Uniswap swap-to-exit                  | Emergency toggle available |
| Dynamic pricePerShare    | Fixed 1:1 + side-stream rewards       | Accruing share price       |


# Rewards

USDREFI uses [Merkl](https://merkl.xyz/) for reward distribution. Merkl is a production-grade off-chain computation / on-chain claim system that distributes rewards pro-rata to qualifying holders without requiring staking or lock-ups.

## How It Works

1. The Reward Safe deposits USDREFI + $REFI into a Merkl campaign at a fixed % rate set by the Foundation
2. Merkl takes periodic snapshots of qualifying USDREFI balances
3. Merkl computes pro-rata shares and builds a Merkle tree
4. The Merkle root is published on-chain
5. Users claim their rewards by submitting a proof — no gas-heavy distribution transactions needed

## Holder Rewards

USDREFI holders earn rewards simply by holding tokens in their wallet. No staking required.

**Eligibility filtering:** Merkl excludes the Uniswap pool contract address from holder reward calculations. Only tokens held in user wallets and allowlisted Safes earn holder rewards. This prevents double-counting tokens that are providing liquidity.

## LP Incentives (Separate)

Liquidity providers on the Uniswap V4 USDREFI/USDC pool are rewarded through a **separate** Merkl campaign or $REFI gauge, independent of holder rewards. This is critical because the pool is the sole exit mechanism — incentives must be attractive enough to maintain sufficient depth.

## Reward Parameters

| Parameter            | Value                                       |
| -------------------- | ------------------------------------------- |
| Reward rate          | Fixed % (set by Foundation Safe)            |
| Reward tokens        | USDREFI + $REFI                             |
| Holder eligibility   | EOAs + allowlisted Safes                    |
| LP eligibility       | Uniswap V4 LP positions (separate campaign) |
| Claim mechanism      | Merkle proof (on-chain)                     |
| Distribution cadence | Monthly                                     |

## Claiming & Compounding

Users can claim rewards at any time via the frontend at `app.regenerative.fi/usdrefi`. The claim modal shows your claimable USDREFI and $REFI balances, and executes a Merkl claim transaction with the appropriate Merkle proof.

A **compound option** is available: claim USDREFI rewards and immediately re-deposit them into the vault in a single flow, increasing your position without additional USDC.


# Identity and Tiers

Access to the USDREFI vault is gated by a progressive identity system. Every depositor must hold a valid Self verification. Higher deposit caps unlock via Prosperity Pass levels.

The vault itself contains zero identity logic — it simply reads a tier number from the TierRegistry.

## Architecture: API → Registry → Vault

The identity system has three layers:

1. **Off-chain API** — Checks Self verification status and Prosperity Pass level, determines tier (1, 2, or 3)
2. **On-chain TierRegistry** — Stores the result as a simple `mapping(address → uint8)`, writable by the API signer and Foundation Safe
3. **Vault** — Calls `tierRegistry.tierOf(receiver)` during deposit and applies the tier cap. No identity awareness beyond the tier number.

This design means tier logic can change — new providers, different thresholds, governance overrides — without redeploying the vault or registry. Only the API needs updating.

## Tier Definitions

| Tier                 | Eligibility                     | Per-User Cap   | Assigned By     |
| -------------------- | ------------------------------- | -------------- | --------------- |
| **0** (unregistered) | No Self verification            | Cannot deposit | —               |
| **1**                | Self verified                   | $500           | API (automatic) |
| **2**                | Self + Prosperity Pass Level 3+ | $5,000         | API (automatic) |
| **3**                | Self + Prosperity Pass Level 5+ | $15,000        | API (automatic) |

## Self Verification

[Self](https://self.xyz/) provides the baseline identity layer. Every depositor must complete Self verification, confirming they are a unique human via self-sovereign cryptographic attestation. The API checks this off-chain before assigning any tier.

## Prosperity Pass

[Prosperity Pass](https://prosperity.celo.org/) is Celo's on-chain reputation system built on Safe infrastructure by CeloPG and Kolektivo Labs. Users link wallets, claim badges for governance participation, events, and on-chain activity, earning Prosperity Points that determine their level.

The API maps Prosperity Pass levels to deposit tiers:

* **Level 3+** → Tier 2 ($5,000 cap)
* **Level 5+** → Tier 3 ($15,000 cap)

## TierRegistry Contract

A minimal on-chain contract storing per-address tier assignments:

```solidity
mapping(address => uint8) public tierOf;

function setTier(address user, uint8 tier) external onlyAuthorized;
function setTierBatch(address[] users, uint8[] tiers) external onlyAuthorized;

// Authorized: API signer + Foundation Safe (admin override)
```

The TierRegistry is intentionally generic. Future identity providers, reputation systems, or governance-based allowlisting can all feed into the same interface without changes to the vault or registry contracts.


# Capital Flow

USDREFI has three primary flows: deposits in, yield cycling, and exits out.

## Deposit Flow

| Step | Action                                                | Actor           |
| ---- | ----------------------------------------------------- | --------------- |
| 1    | User approves USDC spend to vault                     | User wallet     |
| 2    | User calls `vault.deposit(amount, receiver)`          | User wallet     |
| 3    | Vault checks `tierRegistry.tierOf(receiver)` and caps | Vault contract  |
| 4    | Vault mints USDREFI to receiver at 1:1                | Vault contract  |
| 5    | Foundation Safe transfers USDC to Textile/Quipu pool  | Foundation Safe |

Step 5 is a manual operation performed by the Foundation multisig. Deposited USDC sits in the vault until the Safe operators deploy it into the curated credit pool.

## Yield Cycle

| Step | Action                                                  | Cadence      |
| ---- | ------------------------------------------------------- | ------------ |
| 1    | Quipu/Textile reports yield accrual                     | Monthly      |
| 2    | Foundation Safe receives yield                          | Monthly      |
| 3    | Foundation Safe transfers reward portion to Reward Safe | Monthly      |
| 4    | Reward Safe funds Merkl campaign (USDREFI + $REFI)      | Monthly      |
| 5    | Merkl snapshots holders and builds Merkle tree          | Configurable |
| 6    | Users claim rewards via on-chain proofs                 | On-demand    |

## Exit Flow (Swap-Only)

Users swap USDREFI for USDC on the Uniswap V4 concentrated liquidity pool, which targets a \~1:1 price in a tight range (0.995–1.005).

The Uniswap pool is the **only exit path** under normal operations:

* Protocol-owned liquidity (\~$5k) seeds the initial position
* LP incentives via a separate Merkl campaign maintain ongoing depth
* Dune dashboard monitors pool health in real-time
* If liquidity drops below threshold, the Foundation Safe can toggle emergency vault withdrawals

## Foundation Safe

Gnosis Safe with 2-of-3 threshold. Signers: Monty, Luuk, and one additional trusted party. Responsibilities:

* Hold deposited USDC and deploy to Textile/Quipu
* Receive yield returns and transfer reward portion to Reward Safe
* Set/adjust vault parameters (global cap, per-tier caps)
* Override TierRegistry entries and change API signer address
* Toggle emergency withdrawals

## Reward Safe

Separate Gnosis Safe (same signers) holding USDREFI + $REFI for distribution. Funded periodically by the Foundation Safe from yield proceeds. Deposits tokens into Merkl campaigns.


# Uniswap Pool

The Uniswap V4 USDREFI/USDC pool is the **sole exit path** for USDREFI holders under normal operations. It functions as a concentrated liquidity pool designed to maintain a tight peg around $1.

## Pool Parameters

| Parameter     | Value                                  |
| ------------- | -------------------------------------- |
| Pair          | USDREFI / USDC                         |
| Target price  | 1.000                                  |
| Price range   | 0.995 – 1.005                          |
| Fee tier      | 0.01% or 0.05%                         |
| Initial POL   | \~$5,000 from treasury                 |
| LP incentives | Separate Merkl campaign or $REFI gauge |
| Chain         | Celo mainnet                           |

## Why Swap-Only Exit

USDREFI does not allow direct vault withdrawals because the underlying capital is deployed into real-world lending with fixed durations. The vault cannot instantly liquidate these positions to honour redemptions. Instead, the Uniswap pool provides continuous secondary market liquidity, allowing holders to exit at market price.

This is a deliberate design choice — not a limitation. It keeps the vault simple, avoids redemption-run risk on illiquid underlying assets, and aligns exit liquidity with actual market demand.

## Protocol-Owned Liquidity (POL)

The protocol seeds the pool with \~$5,000 of initial liquidity from the treasury. This ensures the pool has baseline depth from day one, before external LPs join. As the protocol earns yield surplus, additional capital is allocated to deepen POL over time.

## LP Incentives

External LPs are incentivised through a separate Merkl campaign distributing $REFI tokens. Since the pool is the only exit mechanism, maintaining healthy depth is critical — LP incentives are sized accordingly.

## Liquidity Risk Management

Several safeguards monitor and protect pool health:

* **Dune dashboard** tracks pool depth, trade volume, and USDREFI/USDC price ratio in real-time
* **Alerts** fire if liquidity drops below a safety threshold
* **Frontend warnings** show pool liquidity and estimated price impact before any swap
* **Recommended max swap** is $2,000 — amounts above this trigger a red warning with a mandatory confirmation checkbox
* **Emergency fallback** — the Foundation Safe can enable direct vault withdrawals if the pool loses critical liquidity

## For Users: Exiting USDREFI

To exit your position:

1. Go to the Swap-to-Exit section in the app
2. Enter the amount of USDREFI you want to sell
3. Review the Uniswap quote: estimated USDC received, pool liquidity, and price impact
4. Confirm the swap

The swap routes through the Uniswap V4 swap router. The price should be close to 1:1 under normal conditions, but this is a market swap — not a vault redemption — so the price may differ slightly.


# Vault

The vault is a standard ERC-4626 tokenized vault with **USDC as the underlying asset** and **USDREFI as the share token**. Because yield is distributed as a side-stream via Merkl (rather than accruing into the share price), the exchange rate is always **1:1**.

## Deposit Functions (Active)

| Function                         | Behavior                                                                    |
| -------------------------------- | --------------------------------------------------------------------------- |
| `deposit(assets, receiver)`      | Accepts USDC, mints USDREFI 1:1. Checks tier and caps. Reverts if tier = 0. |
| `mint(shares, receiver)`         | Same logic, denominated in shares.                                          |
| `maxDeposit(receiver)`           | Returns `min(globalRemaining, tierCapRemaining)`. Returns 0 if tier = 0.    |
| `maxMint(receiver)`              | Equivalent to maxDeposit at 1:1 rate.                                       |
| `previewDeposit` / `previewMint` | Identity function (1:1).                                                    |

## Withdrawal Functions (Disabled)

| Function                    | Behavior                                        |
| --------------------------- | ----------------------------------------------- |
| `maxWithdraw` / `maxRedeem` | Return 0 — signals withdrawals unavailable.     |
| `withdraw` / `redeem`       | Revert with message directing users to Uniswap. |

{% hint style="info" %}
The Foundation Safe can call `setWithdrawalsEnabled(true)` to re-enable withdrawals in an emergency. This toggle can be reversed once the Uniswap pool is restored.
{% endhint %}

## Cap System

| Parameter           | Initial Value | Governance                                   |
| ------------------- | ------------- | -------------------------------------------- |
| Global vault cap    | $25,000 USDC  | `setGlobalCap(uint256)` via Foundation Safe  |
| Tier 1 per-user cap | $500 USDC     | `setTierCap(1, uint256)` via Foundation Safe |
| Tier 2 per-user cap | $5,000 USDC   | `setTierCap(2, uint256)` via Foundation Safe |
| Tier 3 per-user cap | $15,000 USDC  | `setTierCap(3, uint256)` via Foundation Safe |

The `maxDeposit` function enforces both the global cap and the per-user tier cap, returning the lower of the two remaining amounts.

## ERC-4626 Compliance

The vault is fully ERC-4626 compliant despite disabled withdrawals. The standard explicitly allows `maxWithdraw()` and `maxRedeem()` to return 0, signaling to integrators that withdrawals are unavailable. Portfolio trackers (DeBank, Zapper) will correctly display the position, and all deposit-side view functions work normally.

## Implementation Notes

* Built on OpenZeppelin's ERC4626 base with overrides for `maxDeposit`, `maxMint`, `maxWithdraw`, `maxRedeem`, `deposit` (cap checks), and `totalAssets`
* `totalAssets()` uses an internal counter — not `token.balanceOf(address(this))` — to avoid counting dust or direct transfers
* First-depositor inflation attack is not a risk at fixed 1:1 pricing
* `maxDeposit` never overestimates — returns 0 on any overflow rather than reverting