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

packages/kit/src/views/Earn/

packages/kit/src/views/Borrow/

packages/kit/src/views/Staking/

packages/shared/src/routes/

packages/kit/src/routes/Modal/router.tsx

packages/kit/src/routes/Tab/router.ts

Common Components

StakingAmountInput

Staking/components/

StakingFormWrapper

Staking/components/

EarnText

Staking/components/ProtocolDetails/

EarnTooltip

Staking/components/ProtocolDetails/

PendingIndicator

Staking/components/StakingActivityIndicator/

ManagePositionContent

Staking/pages/ManagePosition/

ManagePosition

Borrow/components/ManagePosition/

State Management Patterns

IAsyncData<T>

DataGate

PendingBridge

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:

1k-i18n

ETranslations

useIntl()

1k-coding-patterns

1k-cross-platform

platformEnv

page-and-route

i18n Quick Reference

All user-facing strings must use internationalization. See

1k-i18n

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