diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 1def665708..6ccccf9755 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -1,3 +1,264 @@ -# How to contribute +# Contributing to Freighter -Please read the [Contribution Guide](https://github.com/stellar/.github/blob/master/CONTRIBUTING.md). \ No newline at end of file +Non-custodial Stellar wallet browser extension. Monorepo with extension, client +SDK, shared utilities, and docs site. + +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 | >= 22 | `nvm use` (reads `.nvmrc`) | +| Yarn | 4.10.0 | `corepack enable && corepack prepare yarn@4.10.0 --activate` | +| Chrome or Firefox | Latest | For loading and testing the extension | + +## 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 LLM 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 +the `freighter-best-practices` guide (located in +`docs/skills/freighter-best-practices/` once available). + +The skill will: + +1. Check all prerequisites (Node, Yarn, Chrome/Firefox) +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 the public backend endpoints +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.git +cd freighter +nvm use # Switches to Node 22 +yarn setup # Installs dependencies and allows scripts +``` + +### Environment Variables + +Create `extension/.env`: + +```env +INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 +INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 +``` + +These are the public production endpoints — the only required variables for +local development. To run your own backend, see +[stellar/freighter-backend](https://github.com/stellar/freighter-backend) (V1) +and +[stellar/freighter-backend-v2](https://github.com/stellar/freighter-backend-v2) +(V2). + +### Run the Extension + +```bash +yarn start # Starts all workspaces in parallel +``` + +This runs the extension dev server (`localhost:9000`), SDK build in watch mode, +and Docusaurus (`localhost:3000`). + +To start a single workspace: `yarn start:extension`, `yarn start:freighter-api`, +or `yarn start:docs`. + +**Load in Chrome:** + +1. Go to `chrome://extensions`, enable "Developer mode" +2. Click "Load unpacked", select `extension/build/` + +**Load in Firefox:** + +1. Go to `about:debugging#/runtime/this-firefox` +2. Click "Load Temporary Add-on", select `extension/build/manifest.json` + +### Hot Reload + +- **Popup changes** hot reload via the dev server at `localhost:9000` +- **Background/content script changes** require `yarn build:extension` + reload + the extension in the browser + +### Dev URLs + +| URL | Purpose | +| ----------------------------------- | ----------------------- | +| `localhost:9000` | Extension popup | +| `localhost:9000/#/debug` | Blockaid debug panel | +| `localhost:9000/#/integration-test` | Integration test helper | +| `localhost:3000` | Documentation site | + +## Key Commands + +```bash +yarn build:extension # Dev build +yarn build:extension:experimental # Experimental features enabled +yarn build:extension:production # Minified production build +yarn test # Jest unit tests (watch mode) +yarn test:ci # Jest CI mode (no watch) +yarn test:e2e # Playwright e2e tests +``` + +See `package.json` for the complete list of scripts. + +## Code Conventions + +- **Formatting:** Double quotes, 2-space indent, trailing commas, 80-char width, + semicolons. Enforced by Prettier (`.prettierrc.yaml`). +- **Linting:** ESLint with auto-fix. Config in `eslint.config.js`. +- **Navigation:** Use `navigateTo` helper + `ROUTES` enum — never hardcoded + paths. See [`extension/STYLEGUIDE.MD`](extension/STYLEGUIDE.MD). +- **Imports:** Keep external packages first, then internal. +- **Translations:** All user-facing strings through `t()` from `react-i18next`. + See [`extension/LOCALIZATION.MD`](extension/LOCALIZATION.MD). + +### Pre-commit Hooks + +Husky runs on every commit: + +1. `./.husky/addTranslations.sh` — auto-generates locale files +2. `pretty-quick --staged` — runs Prettier on staged files + +If using nvm, create `~/.huskyrc` to ensure the correct Node version loads. + +## Architecture + +The extension has three runtime contexts communicating via message passing: + +| Context | Location | Purpose | +| ------------------ | ------------------------------ | ----------------------------------------------------------- | +| **Popup** | `extension/src/popup/` | React app — UI the user sees | +| **Background** | `extension/src/background/` | Service worker — keys, signing, storage, message handling | +| **Content Script** | `extension/src/contentScript/` | Bridges `window.postMessage` from dApps to `chrome.runtime` | + +**Monorepo structure:** + +``` +freighter/ +├── extension/ # Browser extension (popup, background, content script) +├── @stellar/freighter-api/ # npm SDK for dApp integration +├── @shared/ # Shared code (api, constants, helpers) +├── docs/ # Docusaurus site (docs.freighter.app) +└── config/ # Shared build configs +``` + +## Testing + +**Unit tests:** Jest with JSDOM. Tests in `__tests__/` alongside source. Run +`yarn test` (watch) or `yarn test:ci`. + +**E2E tests:** Playwright with Chromium. See +[`extension/e2e-tests/README.md`](extension/e2e-tests/README.md) for setup and +writing tests. + +```bash +yarn test:e2e # All tests +yarn test:e2e sendPayment.test.ts # Specific file +yarn test:e2e --ui # Interactive mode +``` + +**Before submitting a PR:** `yarn test:ci` must pass. Test on both Chrome and +Firefox when touching extension behavior. + +## Adding Features + +### Adding a new feature end-to-end + +A typical extension feature touches all three runtime contexts: + +1. **Popup** — add the UI in `extension/src/popup/` (React component + route) +2. **Background** — add the handler in `extension/src/background/` (message + listener, storage, or signing logic) +3. **Content Script** — if the feature involves dApp communication, add the + message relay in `extension/src/contentScript/` + +Use typed message enums for popup <-> background <-> content script +communication. Follow existing patterns in the codebase. + +### Adding a new API method to `@stellar/freighter-api` + +1. Add the method in `@stellar/freighter-api/src/` +2. Add the corresponding message handler in `extension/src/background/` +3. Add the content script relay in `extension/src/contentScript/` +4. Add an interactive playground in `docs/docs/playground/` +5. Update the API docs at `docs.freighter.app` + +### Running the backend locally + +The extension connects to two separate backend services: + +- **V1** `INDEXER_URL` → + [stellar/freighter-backend](https://github.com/stellar/freighter-backend) + (TypeScript) — balances, subscriptions, feature flags, notifications +- **V2** `INDEXER_V2_URL` → + [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. Update `INDEXER_URL` and/or `INDEXER_V2_URL` in `extension/.env` to point at + your local instance + +## Pull Requests + +- Branch from `master` with a type prefix: `feature/`, `fix/`, `chore/`, + `refactor/`, `bugfix/` +- 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 +- Update translations if adding user-facing strings (pre-commit hook handles + generation) +- Test on both Chrome and Firefox + +**CI runs on every PR:** Jest + Playwright (`runTests.yml`), CodeQL security +analysis (`codeql.yml`). All must pass. + +## Security + +Freighter handles private keys and signs transactions. When contributing: + +- **Never log or expose** private keys, seed phrases, or passwords +- **Validate all external data** — dApp messages via content script, API + responses +- **Don't bypass CSP** or weaken existing security guardrails +- **Be careful with `window.postMessage`** — the content script is an attack + surface +- **Use production builds** for testing security-sensitive flows (extra + guardrails) +- **Report vulnerabilities** via the + [Stellar Security Policy](https://github.com/stellar/.github/blob/master/SECURITY.md) + — not public issues + +## Further Reading + +| Topic | Location | +| --------------------------- | -------------------------------------------------------------------------------------- | +| Extension dev guide | [`extension/README.md`](extension/README.md) | +| Hardware wallet integration | [`extension/INTEGRATING_HARDWARE_WALLET.MD`](extension/INTEGRATING_HARDWARE_WALLET.MD) | +| Soroswap integration | [`extension/INTEGRATING_SOROSWAP.MD`](extension/INTEGRATING_SOROSWAP.MD) | +| Localization guide | [`extension/LOCALIZATION.MD`](extension/LOCALIZATION.MD) | +| Style guide | [`extension/STYLEGUIDE.MD`](extension/STYLEGUIDE.MD) | +| E2E testing | [`extension/e2e-tests/README.md`](extension/e2e-tests/README.md) | +| API playgrounds | [docs.freighter.app](https://docs.freighter.app) | +| All scripts & commands | `package.json` | +| Best practices (LLM guide) | `docs/skills/freighter-best-practices/` (once available) | + +**Questions?** Open a +[GitHub Discussion](https://github.com/stellar/freighter/discussions) or join +the [Stellar Developer Discord](https://discord.gg/stellardev). diff --git a/README.md b/README.md index 82313be3d4..7fb40b7ec9 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,12 @@ This repo is constructed using yarn workspaces and consists of the 4 sections: ## Prerequisites -You will need +- Node (>= 22): https://nodejs.org/en/download/ (use `nvm use` — the repo has + `.nvmrc`) +- Yarn 4.10.0: `corepack enable && corepack prepare yarn@4.10.0 --activate` -- Node (>=21): https://nodejs.org/en/download/ -- Yarn (v1.22.5 or newer): https://classic.yarnpkg.com/en/docs/install +For a complete setup guide including LLM-assisted quick setup, see +[CONTRIBUTING.MD](CONTRIBUTING.MD). ## Build the extension @@ -46,7 +48,7 @@ file `extension/.env` with the following variables: ``` INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 -INDEXER_V2_URL=https://freighter-backend-v2-prd.stellar.org/api/v1 +INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 ``` These URLs point to the production Freighter backend. For more details on diff --git a/quick-start-guide.md b/quick-start-guide.md new file mode 100644 index 0000000000..58900dd600 --- /dev/null +++ b/quick-start-guide.md @@ -0,0 +1,150 @@ +# Freighter Extension — Quick Start Guide + +Evaluate the contributor's machine against all prerequisites for Freighter +(browser extension), 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 >= 22 +node --version 2>&1 || which node + +# nvm (needed for node version management — repo has .nvmrc) +if command -v nvm >/dev/null 2>&1 || test -d "$HOME/.nvm"; then echo "nvm found"; else echo "nvm missing"; fi + +# Corepack +corepack --version 2>&1 || which corepack + +# Yarn 4.10.0 +yarn --version 2>&1 || which yarn + +# Browser (at least one needed for testing the extension) +# macOS +if [ "$(uname -s)" = "Darwin" ]; then + test -d "/Applications/Google Chrome.app" && echo "Chrome: found" || echo "Chrome: not found" + test -d "/Applications/Firefox.app" && echo "Firefox: found" || echo "Firefox: not found" +else + # Linux/other + command -v google-chrome >/dev/null 2>&1 || command -v google-chrome-stable >/dev/null 2>&1 || command -v chromium >/dev/null 2>&1 || command -v chromium-browser >/dev/null 2>&1 + test $? -eq 0 && echo "Chrome: found" || echo "Chrome: not found" + command -v firefox >/dev/null 2>&1 && echo "Firefox: found" || echo "Firefox: not found" +fi + +# Playwright (for e2e tests — installed via yarn, just check availability) +npx playwright --version 2>&1 || echo "Playwright: will be installed via yarn" +``` + +## Step 2: Present results + +Show a clear summary: + +``` +Freighter Extension — Prerequisites Check +========================================== + Node.js v22.x.x >= 22 required OK + nvm found any OK + Corepack 0.x.x any OK + Yarn 4.10.0 4.10.0 required OK + Chrome found at least one browser OK + Firefox not found (Chrome is enough) OK + Playwright via yarn for e2e tests OK +``` + +## Step 3: Install missing tools + +Present the missing tools and 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** (macOS): + `/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: + `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"` +- **Node.js 22**: `nvm install 22` +- **Corepack + Yarn**: + `corepack enable && corepack prepare yarn@4.10.0 --activate` +- **Chrome**: `brew install --cask google-chrome` (macOS) or install via system + package manager (Linux) + +**Manual — guide the user:** + +- If using nvm, create `~/.huskyrc` so pre-commit hooks load the correct Node + version: + ```bash + export NVM_DIR="$HOME/.nvm" + [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" + ``` + +## Step 4: Run initial setup + +```bash +nvm use # Switch to Node 22 (.nvmrc) +yarn setup # Install deps + allow scripts +``` + +## Step 5: Configure environment + +Check if `extension/.env` exists. If not, create it with the required variables: + +```env +INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 +INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 +``` + +These are the public production endpoints — the only required variables for +local development. To run your own backend, see +[stellar/freighter-backend](https://github.com/stellar/freighter-backend) (V1) +and +[stellar/freighter-backend-v2](https://github.com/stellar/freighter-backend-v2) +(V2). + +If `extension/.env` already exists, verify it has both `INDEXER_URL` and +`INDEXER_V2_URL` set. + +## Step 6: Verify + +```bash +yarn build:extension +``` + +If the build succeeds, tell the user they're ready: + +1. Run `yarn start` +2. Open `chrome://extensions` (or `about:debugging` in Firefox) +3. Load unpacked from `extension/build/` +4. The popup is at `localhost:9000` + +If the build fails, read the error and diagnose — common causes are missing +`.env` vars or wrong Node version. + +## Step 7: Summary + +At the end, produce a final summary: + +``` +Setup Complete +============== + Installed: [list of tools installed] + Configured: extension/.env with backend endpoints + + Ready to run: + 1. yarn start + 2. Load extension/build/ in Chrome (chrome://extensions > Load unpacked) + 3. Popup at localhost:9000 +```