Scenario	Description	Guide
New Protocol in Earn	Adding a staking/yield protocol (e.g., Lido, Rocket Pool)	earn-module-guide.md
New Protocol in Borrow	Adding a lending market (e.g., Aave, Compound)	borrow-module-guide.md
Entirely New Module	Creating a new DeFi category (e.g., Pendle, GMX)	new-module-guide.md

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:

The protocol type is ambiguous (could be Earn or Borrow)
The operation types are not standard
Special UI/UX requirements are mentioned
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

Decision	Options	Default
Integration type	Earn / Borrow / New Module	Ask user
Tab placement	Existing Earn Tab / New Tab	Earn Tab
Operation count	2-3 (Earn) / 4 (Borrow) / Custom	Based on type
Risk warnings	Liquidation / Slashing / None	Based on type
Token selection	Single / Multiple	Single
Charts	APY history / Interest model / None	Based on type
Share feature	Yes / No	Yes
Multi-token list	Yes / No	Based on token count
Time-based features	Maturity date / Conditional ops / None	Based on protocol
Multi-variant assets	Group by underlying / Flat list	Based on protocol
Operation tabs	Single op / Tab switching (Buy/Sell/Redeem)	Based on protocol
Repay with collateral	Wallet balance only / With collateral option	Based on protocol
Dual amount input	Single input / Bidirectional sync	Based on operation
Slippage settings	Not needed / Auto / Custom	Based on swap involvement

State Management Decision

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

State Type	Recommendation	Examples
Needs Persistence (across page navigation)	Use Jotai atoms	Portfolio data, user preferences, cached investments
Page-scoped (no persistence needed)	Use React Context	Current operation state, form data, temporary UI state

When using this skill, you should:

Analyze the state requirements of the new module
Ask the user whether the state needs to persist across page navigation
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

Module	Path
Earn	`packages/kit/src/views/Earn/`
Borrow	`packages/kit/src/views/Borrow/`
Staking (shared)	`packages/kit/src/views/Staking/`
Routes	`packages/shared/src/routes/`
Modal Router	`packages/kit/src/routes/Modal/router.tsx`
Tab Router	`packages/kit/src/routes/Tab/router.ts`

Common Components

Component	Location	Usage
`StakingAmountInput`	`Staking/components/`	Amount input with validation
`StakingFormWrapper`	`Staking/components/`	Form layout wrapper
`EarnText`	`Staking/components/ProtocolDetails/`	Styled text with color support
`EarnTooltip`	`Staking/components/ProtocolDetails/`	Info tooltips
`PendingIndicator`	`Staking/components/StakingActivityIndicator/`	Pending tx indicator
`ManagePositionContent`	`Staking/pages/ManagePosition/`	Shared manage position UI
`ManagePosition`	`Borrow/components/ManagePosition/`	Unified Borrow operation component (Supply/Withdraw/Borrow/Repay)

State Management Patterns

Pattern	Use Case	Reference
`IAsyncData<T>`	Unified async data format	state-management-guide.md
`DataGate`	Data orchestration	state-management-guide.md
`PendingBridge`	External pending state	state-management-guide.md
Tag System	Pending tx identification	state-management-guide.md

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:

Skill	Use For
`1k-i18n`	Adding translations, using `ETranslations`, `useIntl()`
`1k-coding-patterns`	React patterns, error handling, TypeScript best practices
`1k-cross-platform`	Platform-specific code, `platformEnv` checks
`page-and-route`	Route configuration, deep links, navigation

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:

Add key to ETranslations enum in packages/shared/src/locale/enum.ts
Add translations in locale JSON files
Never hardcode user-facing strings

Reference Documents

Document	Content
earn-module-guide.md	Earn module architecture, files, operations
borrow-module-guide.md	Borrow module architecture, 4 operations, health factor
new-module-guide.md	Creating new modules, Provider design
routing-guide.md	Modal routes, Tab routes, navigation utilities, deep links
state-management-guide.md	IAsyncData, Pending, Tag system, refresh strategies
checklist.md	Integration checklist with required/optional markers