diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a78bd607 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,300 @@ +# Contributing to Freighter Mobile + +Non-custodial Stellar wallet for iOS and Android. Built with React Native, +Zustand, and React Navigation. + +For the Stellar organization's general contribution guidelines, see the +[Stellar Contribution Guide](https://github.com/stellar/.github/blob/master/CONTRIBUTING.md). + +## Prerequisites + +| Tool | Version | Install | +| -------------- | ------------- | ----------------------------------------------------------------- | +| Node.js | >= 20 | [nodejs.org](https://nodejs.org) or `nvm install 20` | +| Yarn | 4.10.0 | `corepack enable && corepack prepare yarn@4.10.0 --activate` | +| Ruby | >= 2.6.10 | [rbenv](https://github.com/rbenv/rbenv) or [rvm](https://rvm.io/) | +| Watchman | Latest | `brew install watchman` | +| JDK | 17 | [Adoptium](https://adoptium.net/) or Android Studio | +| Xcode | Latest stable | Mac App Store (iOS only) | +| Android Studio | Latest stable | [developer.android.com](https://developer.android.com/studio) | +| Maestro CLI | Latest | `brew install mobile-dev-inc/tap/maestro` (e2e tests only) | + +**Android SDK requirements** (install via Android Studio SDK Manager): + +- SDK Platform API 36, Build-Tools 36.0.0, NDK 28.2.13676358 + +**Shell environment** — add to `~/.zshrc` or `~/.bashrc`: + +```bash +# macOS +export ANDROID_HOME=$HOME/Library/Android/sdk +# Linux +# export ANDROID_HOME=$HOME/Android/Sdk +# Windows (Git Bash / WSL) +# export ANDROID_HOME=$HOME/AppData/Local/Android/Sdk +export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools +``` + +For full platform setup, see the +[React Native Environment Setup](https://reactnative.dev/docs/set-up-your-environment) +guide. + +## Getting Started + +### Quick Setup with an LLM + +If you use an LLM-powered coding assistant, you can automate the setup. The repo +includes a quick start guide ([`quick-start-guide.md`](quick-start-guide.md)) +that checks your environment, installs missing tools, configures `.env`, and +verifies the build. + +Point your coding assistant at `quick-start-guide.md` and ask it to follow the +steps. + +For detailed best practices and coding guidelines when working with an LLM, see +[`docs/skills/freighter-mobile-best-practices`](docs/skills/freighter-mobile-best-practices/). + +The skill will: + +1. Check all prerequisites (Node, Yarn, Ruby, JDK, Xcode, Android SDK, etc.) +2. Install what it can automatically (with your confirmation) +3. Produce a list of manual steps for anything it couldn't install +4. Set up `.env` with public backend endpoints and guide you through the + remaining variables +5. Run verification to confirm the build works + +If you don't use an LLM assistant, follow the manual setup below. + +### Manual Setup + +```bash +git clone https://github.com/stellar/freighter-mobile.git +cd freighter-mobile +bundle install # Ruby deps (Fastlane, CocoaPods) +yarn install # Node deps + auto-runs postinstall (Husky, polyfills, pods) +cp .env.example .env # Then fill in values (see below) +``` + +### Environment Variables + +Copy `.env.example` to `.env` and fill in the values. The `.env` file must +**never** be committed. + +**Required — app won't build or function without these:** + +| Variable | How to set up | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `FREIGHTER_BACKEND_V1_DEV_URL` | `https://freighter-backend-dev.stellar.org/api/v1`. If unavailable, use `-stg` or `-prd`. Or run your own from [stellar/freighter-backend](https://github.com/stellar/freighter-backend) | +| `FREIGHTER_BACKEND_V2_DEV_URL` | `https://freighter-backend-v2-dev.stellar.org/api/v1`. If unavailable, use `-stg` or prod (`freighter-backend-v2.stellar.org`). Or run your own from [stellar/freighter-backend-v2](https://github.com/stellar/freighter-backend-v2) | +| `WALLET_KIT_PROJECT_ID_DEV` | Create a free project at [dashboard.reown.com](https://dashboard.reown.com) — sign up, create a new project (type: Wallet), copy the Project ID | +| `WALLET_KIT_MT_NAME_DEV` | Your project name from the Reown dashboard | +| `WALLET_KIT_MT_DESCRIPTION_DEV` | Your project description | +| `WALLET_KIT_MT_URL_DEV` | Your project URL | +| `WALLET_KIT_MT_ICON_DEV` | Your project icon URL | +| `WALLET_KIT_MT_REDIRECT_NATIVE_DEV` | Deep link scheme matching your dev bundle ID | +| `ANDROID_DEBUG_KEYSTORE_PASSWORD` | Android Studio's default: `android` | +| `ANDROID_DEBUG_KEYSTORE_ALIAS` | Android Studio's default: `androiddebugkey` | +| `ANDROID_DEV_KEYSTORE_PASSWORD` | Generate your own keystore: `mkdir -p android/keystores && keytool -genkey -v -keystore android/keystores/dev-release.keystore -alias dev -keyalg RSA -keysize 2048 -validity 10000`, then use the password you set | +| `ANDROID_DEV_KEYSTORE_ALIAS` | The alias you chose when generating the keystore (e.g., `dev`) | + +**Optional — features degrade gracefully without these:** + +| Variable | Notes | +| -------------------------------------------- | ------------------------------------------------------------------------------------------ | +| `AMPLITUDE_API_KEY` | Auto-disabled in `__DEV__` mode — not needed for local dev | +| `SENTRY_DSN` | Leave empty — errors log to console instead | +| `FREIGHTER_BACKEND_*_STG_URL` / `*_PROD_URL` | Only needed for staging/prod builds. Same public endpoints with `-stg` or `-prd` subdomain | +| `WALLET_KIT_*_PROD` (6 vars) | Only needed for prod builds — same setup as dev vars above | +| `ANDROID_PROD_KEYSTORE_*` | Only needed for release builds — generate a separate keystore | +| `MP_COLLECTIONS_ADDRESSES` | Comma-separated list — leave empty if not working on collectibles | + +**E2E testing only:** + +| Variable | Notes | +| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `IS_E2E_TEST` | Set to `true` when running Maestro | +| `E2E_TEST_RECOVERY_PHRASE` | Generate a new wallet via any Stellar wallet and copy the 12/24-word phrase (used by `CreateWallet`/`ImportWallet` flows) | +| `E2E_TEST_FUNDED_RECOVERY_PHRASE` | Recovery phrase for a **dedicated low-balance mainnet test wallet only**. **Never use a personal wallet or any wallet holding meaningful funds.** Required by `SendClassicTokenMainnet` and `SwapClassicTokenMainnet` flows which execute real transactions on mainnet. Fund the account with a small amount of XLM before running these tests. | + +See `.env.example` for the full list with inline comments. + +### Run the App + +```bash +yarn ios # iOS simulator (dev) +yarn android # Android emulator (dev) +yarn start # Metro bundler only (starts automatically with above) +``` + +Dev and prod builds use separate bundle IDs (`org.stellar.freighterdev` / +`org.stellar.freighterwallet`) and can coexist on the same device. See +`package.json` for all run commands including device and release variants. + +## Key Commands + +```bash +yarn test # Jest unit tests +yarn check # All checks (TypeScript + ESLint + Prettier) +yarn fix # Auto-fix lint + format +yarn lint:translations # Check for missing i18n keys +yarn test:e2e:ios # Maestro e2e (iOS) +yarn test:e2e:android # Maestro e2e (Android) +``` + +**Cleaning builds** (escalation order): + +```bash +yarn start-c # Clear Metro cache +yarn pod-install # Reinstall CocoaPods +yarn node-c-install # Remove node_modules + reinstall +yarn c-install # Full clean (Gradle + node_modules + reinstall) +yarn r-install # Nuclear: reset env + rebuild everything +``` + +See `package.json` for the complete list of scripts. + +## Repository Structure + +``` +freighter-mobile/ +├── src/ +│ ├── components/ # React Native components (screens, templates, primitives) +│ ├── ducks/ # Zustand state stores +│ ├── hooks/ # Custom React hooks +│ ├── helpers/ # Utility functions +│ ├── services/ # Business logic & API calls +│ ├── navigators/ # React Navigation stack/tab definitions +│ ├── providers/ # Context providers +│ ├── config/ # App configuration +│ ├── types/ # TypeScript type definitions +│ └── i18n/ # Translations (i18next) +├── __tests__/ # Jest unit tests (mirrors src/) +├── e2e/ # Maestro e2e tests + docs +├── ios/ / android/ # Native projects +└── scripts/ # Build and setup scripts +``` + +## Code Conventions + +- **Formatting:** Double quotes, 2-space indent, trailing commas, 80-char width, + semicolons. Enforced by Prettier (`.prettierrc.json`). +- **Linting:** Airbnb + TypeScript strict + custom translations plugin. Config + in `eslint.config.mjs`. +- **Absolute imports:** Always from `src/` root — no relative paths. Enforced by + ESLint. +- **Arrow functions:** Required for React components. Enforced by ESLint. +- **Import sorting:** Auto-handled by `@trivago/prettier-plugin-sort-imports`. +- **JSDoc:** Required on all new/modified public functions (see + [PR template](.github/pull_request_template.md)). +- **Translations:** All user-facing strings through `i18next`. Use + `useAppTranslation` hook. The custom ESLint plugin flags missing translations. + +### Pre-commit Hooks + +Husky runs on every commit: + +1. `lint-staged` — ESLint fix + Prettier on staged files +2. `yarn test` — full unit test suite +3. `yarn lint:ts` — TypeScript type check + +All must pass before the commit succeeds. + +## Testing + +**Unit tests:** Jest with `@testing-library/react-native`. Tests in +`__tests__/`, mocks in `__mocks__/`. + +**E2E tests:** Maestro flows in `e2e/flows/` — see the [e2e docs](e2e/docs/) for +setup, writing tests, and debugging. + +**Before submitting a PR:** `yarn test` + `yarn lint:ts` must pass. Test on both +iOS and Android, including small screens. + +## Adding Features + +### Adding a new screen + +1. Create the screen component in `src/components/screens/` +2. Add the route to `src/config/routes.ts` +3. Register in the appropriate navigator in `src/navigators/` +4. Add translations for all user-facing strings in `src/i18n/` +5. Add tests in `__tests__/` + +### Adding a new Zustand store + +1. Create the store file in `src/ducks/` (e.g., `src/ducks/myFeature.ts`) +2. Define the store using Zustand's `create` with typed state and actions +3. Export a hook for consuming the store (e.g., `useMyFeatureStore`) +4. Add tests in `__tests__/ducks/` + +### Platform-specific code + +- Use `Platform.OS` checks for small differences +- Use `.ios.tsx` / `.android.tsx` file extensions for larger divergences +- Test on **both platforms** — especially native module interactions, gestures, + and keyboard behavior + +## Running the Backend Locally + +The app connects to two separate backend services: + +- **V1** + ([stellar/freighter-backend](https://github.com/stellar/freighter-backend), + TypeScript) — balances, subscriptions, feature flags, notifications +- **V2** + ([stellar/freighter-backend-v2](https://github.com/stellar/freighter-backend-v2), + Go) — collectibles, RPC health, ledger keys, protocols + +To run your own: + +1. Clone the repo for the backend you need (V1, V2, or both) +2. Follow its README for setup +3. Point `FREIGHTER_BACKEND_V1_DEV_URL` and/or `FREIGHTER_BACKEND_V2_DEV_URL` in + your `.env` at your local instance + +## Pull Requests + +- Branch from `main` using your initials + description: `lf-feature-name`, + `cg-fix-token-display` +- Commit messages: start with action verb (`Add`, `Fix`, `Update`, `Improve`) +- No mixed concerns — keep refactoring separate from features +- Include before/after screenshots for UI changes +- Follow the full checklist in the + [PR template](.github/pull_request_template.md) + +**CI runs on every PR:** unit tests (`test.yml`), iOS e2e (`ios-e2e.yml`), +Android e2e (`android-e2e.yml`). All must pass. + +## Security + +Freighter handles private keys and signs transactions. When contributing: + +- **Never log or expose** private keys, seed phrases, or passwords +- **Use `react-native-keychain`** (iOS Keychain / Android Keystore) for secrets + — never AsyncStorage +- **Validate all external data** — WalletConnect payloads, API responses, deep + links +- **Don't weaken Blockaid** transaction scanning or `jail-monkey` jailbreak + detection +- **Report vulnerabilities** via the + [Stellar Security Policy](https://github.com/stellar/.github/blob/master/SECURITY.md) + — not public issues + +See [`docs/auth_flow_diagram.md`](docs/auth_flow_diagram.md) for the full auth +security model. + +## Further Reading + +| Topic | Location | +| -------------------------- | --------------------------------------------------------------------------------------------- | +| Auth architecture | [`docs/auth_flow_diagram.md`](docs/auth_flow_diagram.md) | +| WalletConnect RPC methods | [`docs/walletconnect-rpc-methods.md`](docs/walletconnect-rpc-methods.md) | +| E2E testing (6 guides) | [`e2e/docs/`](e2e/docs/) | +| Mock dApp for testing | [`mock-dapp/README.md`](mock-dapp/README.md) | +| Release process | [`RELEASE.md`](RELEASE.md) | +| All scripts & commands | `package.json` | +| Best practices (LLM guide) | [`docs/skills/freighter-mobile-best-practices`](docs/skills/freighter-mobile-best-practices/) | + +**Questions?** Open a +[GitHub Discussion](https://github.com/stellar/freighter-mobile/discussions) or +join the [Stellar Developer Discord](https://discord.gg/stellardev). diff --git a/README.md b/README.md index 35b183df..2de312dc 100644 --- a/README.md +++ b/README.md @@ -9,44 +9,23 @@ Mobile. ### Prerequisites -1. **Node.js & Yarn:** - - - Install Node.js (LTS version recommended). You can download it from - [nodejs.org](https://nodejs.org/). - - Yarn is the recommended package manager. Install it via npm (which comes - with Node.js): - ```bash - npm install --global yarn - ``` - -2. **Watchman (macOS only):** - - - Watchman is a tool by Facebook for watching changes in the filesystem. It - is highly recommended for performance. - ```bash - brew install watchman - ``` - -3. **React Native CLI:** - - Install the React Native command line interface: - ```bash - npm install --global react-native-cli - ``` - - Alternatively, you might prefer to use `npx react-native ` for - running commands without a global installation. +- **Node.js** >= 20: [nodejs.org](https://nodejs.org/) or `nvm install 20` +- **Yarn** 4.10.0: `corepack enable && corepack prepare yarn@4.10.0 --activate` +- **Ruby** >= 2.6.10: [rbenv](https://github.com/rbenv/rbenv) or + [rvm](https://rvm.io/) +- **Watchman**: `brew install watchman` (macOS) +- **JDK 17**: Required for Android builds +- **Xcode**: Latest stable (iOS, macOS only) +- **Android Studio**: SDK 36, Build-Tools 36.0.0, NDK 28.2.13676358 + +For the full list of prerequisites, environment variable setup, and LLM-assisted +quick setup, see [CONTRIBUTING.md](CONTRIBUTING.md). ### Platform Specific Setup -Follow the official React Native documentation for setting up your environment -for iOS and Android development. This includes installing Xcode (for iOS) and -Android Studio (for Android), along with their respective SDKs and command-line -tools. - -- Go to the - [React Native development environment setup page](https://reactnative.dev/docs/environment-setup). -- Select **"React Native CLI Quickstart"**. -- Follow the instructions for your development OS (macOS, Windows, Linux) and - target OS (iOS, Android). +Follow the +[React Native Environment Setup](https://reactnative.dev/docs/set-up-your-environment) +guide for iOS and Android. ### Project Setup @@ -68,39 +47,22 @@ tools. The project uses `react-native-config` for environment variables. You'll need to set up your environment variables before running the app: - 1. Create a `.env` file in the project root: + 1. Copy the example file and fill in the required values: ```bash - touch .env - ``` - - 2. Add the required environment variables: - - ``` - FREIGHTER_BACKEND_V1_PROD_URL=your_backend_v1_prod_url_here - FREIGHTER_BACKEND_V2_PROD_URL=your_backend_v2_prod_url_here - - WALLET_KIT_PROJECT_ID_PROD=your_prod_project_id_here - other variables... + cp .env.example .env ``` - 3. Update the `.env.example` file for documentation, add the same variables - without values: - - ``` - FREIGHTER_BACKEND_V1_PROD_URL= - FREIGHTER_BACKEND_V2_PROD_URL= - - WALLET_KIT_PROJECT_ID_PROD= - other variables... - ``` + See [CONTRIBUTING.md](CONTRIBUTING.md#environment-variables) for the full + list of required variables and how to obtain each value. **Important:** - Never commit the `.env` file to version control - Keep `.env.example` updated with any new environment variables - - If you don't have the required environment variables, ask a team member - for the values + - See [CONTRIBUTING.md](CONTRIBUTING.md#environment-variables) for how to + obtain each variable (public endpoints, Reown dashboard, keystore + generation) **Important** diff --git a/quick-start-guide.md b/quick-start-guide.md new file mode 100644 index 00000000..6e51b110 --- /dev/null +++ b/quick-start-guide.md @@ -0,0 +1,211 @@ +# Freighter Mobile — Quick Start Guide + +Evaluate the contributor's machine against all prerequisites for Freighter +Mobile (React Native), install what's missing, and run the initial setup. + +## Step 1: Check all prerequisites + +Run every check below and collect results. Report all at once — don't stop at +the first failure. + +For each tool, try the version command first. If it fails (e.g., sandbox +restrictions), fall back to `which ` to confirm presence. + +```bash +# Node.js >= 20 +node --version 2>&1 || which node + +# Corepack +corepack --version 2>&1 || which corepack + +# Yarn 4.10.0 +yarn --version 2>&1 || which yarn + +# Homebrew +brew --version 2>&1 || which brew + +# Ruby >= 2.6.10 +ruby --version 2>&1 || which ruby + +# Bundler +bundle --version 2>&1 || which bundle + +# Watchman +watchman --version 2>&1 || which watchman + +# JDK 17 +java -version 2>&1 || which java + +# nvm (needed for node version management) +if command -v nvm >/dev/null 2>&1 || test -d "$HOME/.nvm"; then echo "nvm found"; else echo "nvm missing"; fi + +# Xcode CLI Tools (macOS) +xcode-select -p 2>&1 + +# CocoaPods >= 1.13 (not 1.15.0, not 1.15.1) +pod --version 2>&1 || which pod + +# ANDROID_HOME set +echo "ANDROID_HOME=$ANDROID_HOME" + +# Android SDK components +if [ -n "$ANDROID_HOME" ]; then + sdkmanager_bin="$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" + if [ -x "$sdkmanager_bin" ]; then + sdkmanager_list="$("$sdkmanager_bin" --list 2>/dev/null)" + printf '%s\n' "$sdkmanager_list" | grep -Eq "platforms;android-36([[:space:]]|$)" && echo "SDK Platform 36: OK" || echo "SDK Platform 36: MISSING" + printf '%s\n' "$sdkmanager_list" | grep -Eq "build-tools;36\.0\.0([[:space:]]|$)" && echo "Build-Tools 36.0.0: OK" || echo "Build-Tools 36.0.0: MISSING" + printf '%s\n' "$sdkmanager_list" | grep -Eq "ndk;28\.2\.13676358([[:space:]]|$)" && echo "NDK 28.2.13676358: OK" || echo "NDK 28.2.13676358: MISSING" + else + echo "sdkmanager not available — check Android Studio SDK Manager manually" + fi +fi + +# Maestro (optional — only needed for e2e tests) +maestro --version 2>&1 || which maestro || echo "not installed (optional)" +``` + +## Step 2: Present results + +Show a clear summary with status for each tool: + +``` +Freighter Mobile — Prerequisites Check +======================================== + Node.js v22.x.x >= 20 required OK + Corepack 0.x.x any OK + Yarn 4.10.0 4.10.0 required OK + Homebrew 4.x.x any OK + Ruby 3.x.x >= 2.6.10 required OK + Bundler 2.x.x any OK + Watchman 2024.x any OK + JDK 17.0.x 17 required OK + nvm found any OK + Xcode CLI /path any OK + CocoaPods 1.16.x >= 1.13 OK + ANDROID_HOME /path/to/sdk must be set OK + SDK Platform 36 - OK + Build-Tools 36.0.0 - MISSING + NDK 28.2.13676358 - MISSING + Maestro not found optional SKIP +``` + +## Step 3: Install missing tools + +Present the missing tools grouped by auto-installable vs manual. Then ask the +user: "I can install [list] automatically. Want me to proceed?" + +If the user confirms, **run the install commands** for each missing tool. After +each install, re-check the version to confirm it succeeded. If an install fails, +report the error and continue with the next tool. + +If the user declines, skip to Step 4 and note the missing tools in the final +summary. + +**Auto-installable (run after user confirms):** + +- **Homebrew**: + `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` +- **nvm**: + `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash` + — then source nvm before continuing: + `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"` +- **Node.js 20**: `nvm install 20` +- **Corepack + Yarn**: + `corepack enable && corepack prepare yarn@4.10.0 --activate` +- **Watchman**: `brew install watchman` (macOS) or build from source on Linux +- **rbenv + Ruby**: + `brew install rbenv && rbenv install 3.1.4 && rbenv global 3.1.4` (macOS) or + use system package manager on Linux. **3.1.4 is the CI-validated version.** +- **Bundler**: `gem install bundler` +- **JDK 17**: `brew install openjdk@17` (macOS) or + `sudo apt install openjdk-17-jdk` (Linux) +- **Maestro**: `brew install mobile-dev-inc/tap/maestro` (macOS) or + `curl -Ls "https://get.maestro.mobile.dev" | bash` (Linux) +- **Android SDK components**: + `$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "platforms;android-36" "build-tools;36.0.0" "ndk;28.2.13676358"` + +**Manual — guide the user:** + +- **Xcode** (macOS only): Install from Mac App Store, then: + `xcode-select --install && sudo xcodebuild -license accept` +- **Android Studio**: Install from developer.android.com, then open SDK Manager + for SDK 36 + Build-Tools 36.0.0 + NDK 28.2.13676358 +- **ANDROID_HOME** — add to shell profile: + ```bash + # macOS + export ANDROID_HOME=$HOME/Library/Android/sdk + # Linux + # export ANDROID_HOME=$HOME/Android/Sdk + # Windows (Git Bash / WSL) + # export ANDROID_HOME=$HOME/AppData/Local/Android/Sdk + export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools + ``` +- **JAVA_HOME** — macOS with Homebrew: + `export JAVA_HOME=$(/usr/libexec/java_home -v 17)`. Linux: usually + auto-configured by package manager. + +## Step 4: Run initial setup + +```bash +nvm install 20 && nvm use 20 # No .nvmrc — use explicit version +bundle install # Ruby deps (Fastlane, CocoaPods — no separate pod install needed) +yarn install # Node deps (postinstall handles Husky, polyfills, pods) +``` + +## Step 5: Configure environment + +Check if `.env` exists. If not: + +```bash +cp .env.example .env +``` + +Then read `.env` and check which required variables are empty. For each empty +required variable, tell the user the value or how to set it up: + +| Variable | Value or setup | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `FREIGHTER_BACKEND_V1_DEV_URL` | `https://freighter-backend-dev.stellar.org/api/v1` (preferred). Fallback: `-stg` or `-prd` if dev is unavailable | +| `FREIGHTER_BACKEND_V2_DEV_URL` | `https://freighter-backend-v2-dev.stellar.org/api/v1` (preferred). Fallback: `-stg` or prod (`freighter-backend-v2.stellar.org`) if dev is unavailable | +| `WALLET_KIT_PROJECT_ID_DEV` | Create free project at [dashboard.reown.com](https://dashboard.reown.com) (type: Wallet), copy Project ID | +| `WALLET_KIT_MT_NAME_DEV` | Your project name from Reown dashboard | +| `WALLET_KIT_MT_DESCRIPTION_DEV` | Your project description | +| `WALLET_KIT_MT_URL_DEV` | Your project URL | +| `WALLET_KIT_MT_ICON_DEV` | Your project icon URL | +| `WALLET_KIT_MT_REDIRECT_NATIVE_DEV` | Deep link scheme matching your dev bundle ID | +| `ANDROID_DEBUG_KEYSTORE_PASSWORD` | `android` (default) | +| `ANDROID_DEBUG_KEYSTORE_ALIAS` | `androiddebugkey` (default) | +| `ANDROID_DEV_KEYSTORE_PASSWORD` | Generate: `mkdir -p android/keystores && keytool -genkey -v -keystore android/keystores/dev-release.keystore -alias dev -keyalg RSA -keysize 2048 -validity 10000` | +| `ANDROID_DEV_KEYSTORE_ALIAS` | The alias from your keystore (e.g., `dev`) | + +Skip any variable that already has a value. + +## Step 6: Verify + +```bash +yarn check # TypeScript + ESLint + Prettier +yarn test # Jest unit tests +``` + +If both pass, tell the user they're ready: `yarn ios` or `yarn android`. + +If something fails, read the error and diagnose — common causes are missing env +vars, wrong SDK version, or stale pods/gradle cache. + +## Step 7: Summary + +At the end, produce a final summary: + +``` +Setup Complete +============== + Installed: [list of tools installed] + Configured: .env with X/Y required variables filled + + Manual action needed: + - [ ] Create WalletConnect project at dashboard.reown.com and fill WALLET_KIT_* vars + - [ ] Generate Android dev keystore and fill ANDROID_DEV_KEYSTORE_* vars + + Ready to run: yarn ios / yarn android +```