name: 1k-defi-module-integration
description: Interactive guide for integrating new DeFi modules or protocols into OneKey. Use when adding new DeFi features like staking protocols, lending markets, or entirely new DeFi modules. Triggers on DeFi, protocol, integration, Earn, Borrow, staking, lending, supply, borrow, withdraw, repay, claim, new module, Pendle, Aave, Compound.

DeFi Module Integration Guide

This skill provides interactive guidance for integrating new DeFi modules or protocols into OneKey.

Quick Start

Before starting, determine your integration scenario:

Integration Layers

Each DeFi module consists of 4 layers. Home and Modal are required; Details and List are optional.

┌─────────────────────────────────────────────────────────────┐
│  Layer 1: HOME PAGE (Required)                              │
│  - Overview data (total value, APY, health factor)          │
│  - Asset cards/tables                                       │
│  - Pending transaction tracking                             │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: OPERATION MODALS (Required)                       │
│  - Earn: Stake, Unstake, Claim (2-3 types)                  │
│  - Borrow: Supply, Withdraw, Borrow, Repay (4 types)        │
│  - Amount input, validation, risk warnings                  │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: DETAILS PAGE (Optional)                           │
│  - Charts (APY history, interest rate model)                │
│  - Detailed protocol information                            │
│  - Share functionality                                      │
├─────────────────────────────────────────────────────────────┤
│  Layer 4: PROTOCOL LIST (Optional, for multi-token)         │
│  - List of available protocols/assets                       │
│  - Filtering and sorting                                    │
│  - Navigation to details                                    │
└─────────────────────────────────────────────────────────────┘

Scenario Identification

When to ask the user

Ask for clarification when:
1. The protocol type is ambiguous (could be Earn or Borrow)
2. The operation types are not standard
3. Special UI/UX requirements are mentioned
4. The protocol has unique features not covered by existing patterns

Scenario characteristics

Earn Protocol (Staking/Yield):
- Operations: Stake, Unstake, Claim
- Data: APY, staked amount, rewards
- Examples: Lido, Rocket Pool, Babylon

Borrow Protocol (Lending):
- Operations: Supply, Withdraw, Borrow, Repay
- Data: Health factor, collateral, debt, APY
- Examples: Aave, Compound, Morpho
- Advanced features: Repay with Collateral (swap-based repayment)
- See: borrow-module-guide.md - Repay with Collateral

New Module:
- Operations differ significantly from Earn/Borrow
- Requires independent Tab or unique UI
- Examples: Pendle (PT/YT), GMX (perpetuals)

Time-Based Protocol (Fixed-rate yield):
- Operations: Buy, Sell, Redeem (conditional on maturity)
- Data: Maturity date, implied APY, underlying asset, discount rate
- Special features: Maturity status, conditional operations, multi-variant assets
- Examples: Pendle PT
- Integration: As sub-module of Earn Tab (Fixed-rate category)
- See: earn-module-guide.md - Time-Based Protocols

Key Decision Points

State Management Decision

When integrating a new DeFi module, analyze the state requirements and ask the user:

When using this skill, you should:
1. Analyze the state requirements of the new module
2. Ask the user whether the state needs to persist across page navigation
3. Recommend Jotai for persistent state, Context for page-scoped state

Example question to ask:

"Does this module's data need to persist when the user navigates away and returns? For example:
- If yes (like portfolio data that should be cached): Use Jotai atoms
- If no (like form state that resets on page exit): Use React Context"

Quick Reference

Key File Paths

Common Components

State Management Patterns

Workflow

Step 1: Identify Scenario

• Determine if it's Earn, Borrow, or New Module
• Read the corresponding guide

Step 2: Plan Layers

• Decide which layers to implement (Home + Modal required)
• Identify optional layers needed

Step 3: Implement Layer by Layer

• Follow the guide for each layer
• Use the checklist to verify completion

Step 4: Test and Verify

• Test all operation types
• Verify pending state handling
• Check responsive layout

Related Skills

This skill works best when combined with these other OneKey skills:

i18n Quick Reference

All user-facing strings must use internationalization. See 1k-i18n skill for full details.

Basic Usage:

import { useIntl } from 'react-intl';
import { ETranslations } from '@onekeyhq/shared/src/locale';

function MyComponent() {
  const intl = useIntl();

  return (
    <Text>
      {intl.formatMessage({ id: ETranslations.defi_net_worth })}
    </Text>
  );
}

Common DeFi Translation Keys:
- ETranslations.defi_net_worth - "Net Worth"
- ETranslations.defi_net_apy - "Net APY"
- ETranslations.defi_health_factor - "Health Factor"
- ETranslations.defi_platform_bonus - "Platform Bonus"
- ETranslations.defi_claimable_rewards - "Claimable Rewards"
- ETranslations.global_history - "History"

Adding New Keys:
1. Add key to ETranslations enum in packages/shared/src/locale/enum.ts
2. Add translations in locale JSON files
3. Never hardcode user-facing strings

Reference Documents