reva

完整的 Reva 钱包管理 - 无密码身份验证、PayID 姓名认领、多链加密货币转账到 PayID 或钱包地址、跨网络余额跟踪、帐户详细信息和存款管理

## 概述（中文）

完整的 Reva 钱包管理 - 无密码身份验证、PayID 姓名认领、多链加密货币转账到 PayID 或钱包地址、跨网络余额跟踪、帐户详细信息和存款管理

## 原文

# Reva

**Passwordless authentication and wallet management for Reva users.**

Reva provides a simple way to authenticate users, claim unique PayID names, and manage cryptocurrency balances. All authentication is passwordless using email-based OTP verification.

## Authentication

Reva uses a passwordless authentication flow. Users receive a one-time password (OTP) via email, verify it, and receive an access token for subsequent operations.

### Login/Register Flow

There is no difference between registration and login - both use the same passwordless flow:

1. User provides their email address
2. System sends OTP to the email
3. User provides the OTP code
4. System verifies OTP and returns access token
5. Access token is stored securely for future operations

**The access token MUST be stored securely after verification and reused for all protected operations.**

## Available Commands

### 1. Login or Register

**Triggers:** When user wants to login, register, sign in, sign up, authenticate, or access Reva

**Process:**

1. Ask user for their email address if not provided
2. Call the authentication script to send OTP: `{baseDir}/scripts/send-otp.sh <email>`
3. Inform user that OTP has been sent to their email
4. Ask user to provide the OTP code they received
5. Call the verification script: `{baseDir}/scripts/verify-otp.sh <email> <otp>`
6. If successful, inform user they are now authenticated
7. The access token is automatically stored for future use

### 2. Claim PayID

**Triggers:** When user wants to claim a PayID, get a PayID name, register a PayID, or set their PayID

**Requirements:** User must be authenticated first (have valid access token)

**Process:**

1. Check if user is authenticated by calling: `{baseDir}/scripts/check-auth.sh`
2. If not authenticated, prompt user to login first
3. Ask user for their desired PayID name if not provided
4. Call the claim script: `{baseDir}/scripts/claim-payid.sh <desired_payid>`
5. Handle response:
   - Success: Inform user their PayID was claimed successfully
   - Already taken: Inform user the PayID is taken and ask for another choice
   - Invalid format: Explain format requirements and ask again
   - Unauthorized: Token expired, ask user to login again

### 3. View Balance

**Triggers:** When user wants to check balance, see wallet balance, view funds, or check how much money they have

**Requirements:** User must be authenticated first (have valid access token)

**Process:**

1. Check if user is authenticated by calling: `{baseDir}/scripts/check-auth.sh`
2. If not authenticated, prompt user to login first
3. Call the balance script: `{baseDir}/scripts/get-balance.sh`
4. Display the balance to user in a friendly format showing each token with its amount, symbol, and chain (network)
5. If unauthorized error, token expired - ask user to login again

**Display Format Example:**

```
Your current balance:
- 0.001016 ETH on Base
- 1.97 USDC on Base
- 1.21 USDT on BNB Smart Chain
- 0.80 USDC on BNB Smart Chain
- 0.00088 BNB on BNB Smart Chain
```

### 4. Get User Information

**Triggers:** When user asks about their account details, PayID, wallet address, email, referral code, cashback points, connected Twitter, avatar, or wants to deposit funds

**Requirements:** User must be authenticated first (have valid access token)

**Process:**

1. Check if user is authenticated by calling: `{baseDir}/scripts/check-auth.sh`
2. If not authenticated, prompt user to login first
3. Call the user info script: `{baseDir}/scripts/get-user-info.sh`
4. Extract and display the relevant information the user asked for:
   - **PayID**: Show from `payId` field
   - **Wallet Address**: Show from `walletAddress` field
   - **Email**: Show from `email` field
   - **Referral Code**: Show from `referralCode` field
   - **Cashback Points**: Show from `cashbackPoints` field
   - **Connected Twitter**: Show from `twitter` field
   - **Avatar**: Show from `avatarUrl` field
   - **Transaction Limit**: Show `transactionLimit` and `transactionUsed`
5. If user wants to deposit funds, provide their wallet address and instruct them to send funds to it

**Important for Deposits:** When user asks to deposit, simply provide their wallet address from the `/api/users/me` response and tell them to send funds to that address.

### 5. Send Funds

**Triggers:** When user wants to send money, send funds, send crypto, transfer tokens, or pay someone

**Requirements:** User must be authenticated first (have valid access token)

**Process:**

**CRITICAL: You must parse the user's message and extract all required information to construct a proper transfer payload. Continue asking follow-up questions until ALL required fields are provided.**

1. Check if user is authenticated by calling: `{baseDir}/scripts/check-auth.sh`
2. If not authenticated, prompt user to login first
3. Extract the following information from user's message:
   - **Token Symbol**: USDT, USDC, ETH, BNB, POL, or USD_STABLECOIN (these are the ONLY supported tokens)
   - **Chain Symbol**: ETH, POL, OP, BNB, or BASE (null for USD_STABLECOIN)
   - **Recipient**: PayID name, Twitter username (starts with @), or wallet address
   - **Amount**: Numeric value
4. If ANY field is missing, ask the user a follow-up question to get the missing information
5. Once ALL fields are collected, call: `{baseDir}/scripts/send-funds.sh <tokenSymbol> <chainSymbol> <recipient> <amount>`
6. Display the success message or error to the user

**Recipient Type Detection:**

- **Twitter Username**: If recipient starts with `@`, remove the @ and use as `recipientTwitterUsername`
  - Example: `@aminedd4` → `recipientTwitterUsername: "aminedd4"`
- **Wallet Address**: If recipient starts with `0x`, use as `recipientWalletAddress`
  - Example: `0x1234...` → `recipientWalletAddress: "0x1234..."`
- **PayID Name**: Otherwise, use as `recipientPayid`
  - Example: `aldo` → `recipientPayid: "aldo"`

**USD/Dollar Handling (IMPORTANT):**

When user mentions 'USD', 'dollar', 'dollars', or '$':

- Set `tokenSymbol` to `USD_STABLECOIN` (this is a special marker)
- Set `chainSymbol` to `null` - the system automatically selects the network with the highest USD stablecoin balance
- **DO NOT** ask for network when USD/dollar is mentioned - the system handles this automatically

**Supported Tokens (EXACT ENUMS):**

- `USDT` - Tether
- `USDC` - USD Coin
- `ETH` - Ethereum
- `BNB` - Binance Coin
- `POL` - Polygon
- `USD_STABLECOIN` - For USD/dollar requests (chainSymbol must be null)

**Supported Chains (EXACT ENUMS):**

- `ETH` - Ethereum
- `POL` - Polygon
- `OP` - Optimism
- `BNB` - BNB Chain
- `BASE` - Base
- `null` - Only when tokenSymbol is USD_STABLECOIN

**Parsing Examples:**

Example 1: "send 5 usdt on base to aldo"

```
tokenSymbol: USDT
chainSymbol: BASE
recipientPayid: aldo
recipientTwitterUsername: null
recipientWalletAddress: null
amount: 5
```

Example 2: "transfer 0.3 BNB on bnb to @aminedd4"

```
tokenSymbol: BNB
chainSymbol: BNB
recipientPayid: null
recipientTwitterUsername: aminedd4
recipientWalletAddress: null
amount: 0.3
```

Example 3: "send $10 to chris"

```
tokenSymbol: USD_STABLECOIN
chainSymbol: null
recipientPayid: chris
recipientTwitterUsername: null
recipientWalletAddress: null
amount: 10
```

Example 4: "send 1 eth on ethereum to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

```
tokenSymbol: ETH
chainSymbol: ETH
recipientPayid: null
recipientTwitterUsername: null
recipientWalletAddress: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
amount: 1
```

**Follow-up Question Examples:**

- User: "send some usdt to aldo"
  → Missing: amount, chain
  → Ask: "How much USDT would you like to send, and on which network? (ETH, POL, OP, BNB, or BASE)"

- User: "send 5 usdt to aldo"
  → Missing: chain
  → Ask: "Which network would you like to use? (ETH, POL, OP, BNB, or BASE)"

- User: "send 5 usdt on base"
  → Missing: recipient
  → Ask