morpho-earn

通过向 Morpho（基础）上的 Moonwell 旗舰 USDC 金库供应来赚取 USDC 收益。在存入 USDC、从金库提款、检查头寸/APY 或设置 DeFi 收益的钱包凭证时使用。

# Morpho Earn — Earn safe yield on your USDC

Earn yield on USDC via the Moonwell Flagship USDC vault on Base (Morpho protocol).

**Vault:** `0xc1256Ae5FF1cf2719D4937adb3bbCCab2E00A2Ca`
**Chain:** Base (8453)
**Asset:** USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)

## Why This Vault?

The Moonwell Flagship USDC vault is one of the **safest places to earn yield on Base**:

- **Powers Coinbase** — Provides $20M+ liquidity to Coinbase's BTC/ETH borrow products
- **Blue-chip collateral only** — Loans backed by ETH, cbETH, wstETH, cbBTC
- **Conservative LTV ratios** — Healthy collateral requirements
- **Isolated markets** — Risk is compartmentalized
- **No rehypothecation** — Your USDC isn't lent recursively
- **Battle-tested** — Morpho's codebase is <650 lines, immutable, extensively audited
- **Multi-layer governance** — Moonwell DAO + Block Analitica/B.Protocol curators + Security Council

### Current APY (~4.5-5%)

| Component | APY | Source |
|-----------|-----|--------|
| Base yield | ~4% | Borrower interest |
| Rewards | ~0.5-1% | WELL + MORPHO via Merkl |
| **Total** | **~4.5-5%** | Sustainable, from real demand |

Yields come from real borrowing demand, not unsustainable emissions. Check current APY with `npx tsx status.ts`.

## Quick Start

```bash
cd ~/clawd/skills/morpho-yield/scripts
npm install
npx tsx setup.ts
```

The setup wizard will:
1. Configure your wallet (private key file, env var, or 1Password)
2. Ask your notification preferences (daily/weekly reports)
3. Set compound threshold and auto-compound preference
4. Add monitoring to HEARTBEAT.md automatically

## Commands

### Interactive Setup

```bash
npx tsx setup.ts
```

Guides you through wallet configuration and preferences.

### Check Position & APY

```bash
npx tsx status.ts
```

Returns: current deposit, vault shares, APY, wallet balances.

### Generate Report

```bash
# Telegram/Discord format (default)
npx tsx report.ts

# JSON format (for automation)
npx tsx report.ts --json

# Plain text
npx tsx report.ts --plain
```

Beautiful formatted report showing position, rewards, and estimated earnings.

### Deposit USDC

```bash
npx tsx deposit.ts <amount>
# Example: deposit 100 USDC
npx tsx deposit.ts 100
```

Deposits USDC into the Moonwell vault. Requires sufficient USDC balance and gas (ETH on Base).

### Withdraw

```bash
# Withdraw specific amount of USDC
npx tsx withdraw.ts <amount>

# Withdraw all (redeem all shares)
npx tsx withdraw.ts all
```

### Check Rewards

```bash
npx tsx rewards.ts
```

Returns: claimable MORPHO, WELL, and other reward tokens from Merkl.

### Claim Rewards

```bash
npx tsx rewards.ts claim
```

Claims all pending rewards from Merkl distributor to your wallet.

### Auto-Compound

```bash
npx tsx compound.ts
```

All-in-one command that:
1. Claims any pending rewards from Merkl
2. Swaps reward tokens (MORPHO, WELL) to USDC via Odos aggregator
3. Deposits the USDC back into the vault

## Heartbeat Integration

After setup, your agent monitors the position based on deposit size:

| Deposit Size | Compound Check | Rationale |
|--------------|----------------|-----------|
| $10,000+ | Daily | Large positions accumulate meaningful rewards quickly |
| $1,000-$10,000 | Every 3 days | Balance between gas costs and reward accumulation |
| $100-$1,000 | Weekly | Small rewards need time to exceed gas costs |
| <$100 | Bi-weekly | Minimal positions, compound only when worthwhile |

The agent will:
- Check reward balances at the appropriate frequency
- Compound when rewards exceed your threshold (default: $0.50)
- Send position reports (daily/weekly based on preference)
- Alert you if gas is running low

## Configuration

Config location: `~/.config/morpho-yield/config.json`

```json
{
  "wallet": {
    "source": "file",
    "path": "~/.clawd/vault/morpho.key"
  },
  "rpc": "https://rpc.moonwell.fi/main/evm/8453"
}
```

Preferences: `~/.config/morpho-yield/preferences.json`

```json
{
  "reportFrequency": "weekly",
  "compoundThreshold": 0.50,
  "autoCompound": true
}
```

## Security

⚠️ **This skill manages real funds. Review carefully:**

- Private keys loaded at runtime from your chosen source
- Keys never logged or written to disk by scripts
- All transactions simulated before execution
- Contract addresses verified on each run
- Scripts show transaction preview before sending

### Recommended Setup

1. **Dedicated wallet** — Create a hot wallet just for this skill
2. **Limited funds** — Only deposit what you're comfortable having in a hot wallet
3. **Secure key storage** — Use encrypted file or 1Password
4. **Monitor activity** — Periodically check wallet transactions
5. **Keep gas funded** — Maintain small ETH balance on Base for transactions

## Rewards

The vault earns rewards beyond base APY via [Merkl](https://merkl.xyz):
- **WELL** — Moonwell governance token incentives
- **MORPHO** — Morpho protocol incentives

Rewards update approximately every 8 hours. The `compound.ts` script handles:
1. Claiming rewards from Merkl distributor
2. Swapping tokens to USDC via [Odos](https://odos.xyz) aggregator
3. Depositing USDC back into the vault

## Error Handling

| Error | Cause | Fix |
|-------|-------|-----|
| Insufficient USDC | Not enough USDC in wallet | Bridge/transfer more USDC to Base |
| Insufficient gas | Not enough ETH for tx | Add ETH to wallet on Base |
| Wallet not configured | Missing config | Run `npx tsx setup.ts` |
| RPC error | Network issues | Check RPC URL or try again |
| Swap reverted | Gas underestimate | Script auto-adds 50% buffer |

## Dependencies

Scripts require Node.js 18+. Install deps before first run:

```bash
cd scripts && npm install
```

Packages used:
- `viem` — Ethereum interaction
- `tsx` — TypeScript execution

---

## 中文说明

# Morpho Earn — 用你的 USDC 赚取安全收益

通过 Base 上的 Moonwell 旗舰 USDC 金库（Morpho 协议）赚取 USDC 收益。

**Vault：** `0xc1256Ae5FF1cf2719D4937adb3bbCCab2E00A2Ca`
**Chain：** Base (8453)
**Asset：** USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)

## 为什么选择这个金库？

Moonwell 旗舰 USDC 金库是 **Base 上最安全的收益场所之一**：

- **为 Coinbase 提供支持** —— 为 Coinbase 的 BTC/ETH 借贷产品提供 2000 万美元以上的流动性
- **仅蓝筹抵押品** —— 贷款以 ETH、cbETH、wstETH、cbBTC 作为担保
- **保守的 LTV 比率** —— 健康的抵押品要求
- **隔离市场** —— 风险被分隔开
- **无再抵押** —— 你的 USDC 不会被递归借出
- **久经考验** —— Morpho 的代码库不到 650 行，不可变，经过广泛审计
- **多层治理** —— Moonwell DAO + Block Analitica/B.Protocol 策展人 + 安全委员会

### 当前 APY（约 4.5-5%）

| 组成部分 | APY | 来源 |
|-----------|-----|--------|
| 基础收益 | ~4% | 借款人利息 |
| 奖励 | ~0.5-1% | 通过 Merkl 发放的 WELL + MORPHO |
| **总计** | **~4.5-5%** | 可持续，源自真实需求 |

收益来自真实的借贷需求，而非不可持续的代币增发。用 `npx tsx status.ts` 查看当前 APY。

## 快速开始

```bash
cd ~/clawd/skills/morpho-yield/scripts
npm install
npx tsx setup.ts
```

设置向导将：
1. 配置你的钱包（私钥文件、环境变量或 1Password）
2. 询问你的通知偏好（每日/每周报告）
3. 设置复利阈值和自动复利偏好
4. 自动将监控添加到 HEARTBEAT.md

## 命令

### 交互式设置

```bash
npx tsx setup.ts
```

引导你完成钱包配置和偏好设置。

### 查看持仓与 APY

```bash
npx tsx status.ts
```

返回：当前存款、金库份额、APY、钱包余额。

### 生成报告

```bash
# Telegram/Discord format (default)
npx tsx report.ts

# JSON format (for automation)
npx tsx report.ts --json

# Plain text
npx tsx report.ts --plain
```

精美格式化的报告，展示持仓、奖励和预估收益。

### 存入 USDC

```bash
npx tsx deposit.ts <amount>
# Example: deposit 100 USDC
npx tsx deposit.ts 100
```

将 USDC 存入 Moonwell 金库。需要足够的 USDC 余额和 gas（Base 上的 ETH）。

### 提款

```bash
# Withdraw specific amount of USDC
npx tsx withdraw.ts <amount>

# Withdraw all (redeem all shares)
npx tsx withdraw.ts all
```

### 查看奖励

```bash
npx tsx rewards.ts
```

返回：来自 Merkl 的可领取 MORPHO、WELL 及其他奖励代币。

### 领取奖励

```bash
npx tsx rewards.ts claim
```

将所有待领取的奖励从 Merkl 分发器领取到你的钱包。

### 自动复利

```bash
npx tsx compound.ts
```

一体化命令，完成：
1. 从 Merkl 领取任何待领取的奖励
2. 通过 Odos 聚合器将奖励代币（MORPHO、WELL）兑换为 USDC
3. 将 USDC 重新存入金库

## Heartbeat 集成

设置完成后，你的代理会根据存款规模监控持仓：

| 存款规模 | 复利检查 | 理由 |
|--------------|----------------|-----------|
| $10,000+ | 每日 | 大额持仓能快速积累有意义的奖励 |
| $1,000-$10,000 | 每 3 天 | 在 gas 成本与奖励积累之间取得平衡 |
| $100-$1,000 | 每周 | 小额奖励需要时间才能超过 gas 成本 |
| <$100 | 每两周 | 极小持仓，仅在值得时复利 |

代