DeFi Module Integration Guide Skill

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:

| 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 |

Agent Skills: DeFi Module Integration Guide

Install this agent skill to your local

Skill Files