docs: Document Environment Setup for Contributors (#515)

CONTRIBUTING.md

@@ -2,6 +2,10 @@
 
 Welcome, and thanks for your interest in contributing. This document is your starting point — it covers the contribution workflow, coding standards, and PR guidelines. Deeper references are linked throughout.
 
+**Start here instead (recommended):**
+
+- Environment setup (tools, clone, verify): [`docs/ENVIRONMENT_SETUP.md`](docs/ENVIRONMENT_SETUP.md)
+- Development workflow (fork, branch, PR): [`CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md`](CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md)
 ---
 
 ## Documentation Map
@@ -25,6 +29,46 @@ Welcome, and thanks for your interest in contributing. This document is your sta
 ## Code of Conduct
 
 - Be respectful and inclusive
+- Provide constructive feedback
+- Focus on what is best for the community
+- Show empathy towards other contributors
+
+## Getting Started
+
+### Prerequisites
+
+To contribute to NotifyChain, install the tools listed in
+[`docs/ENVIRONMENT_SETUP.md`](docs/ENVIRONMENT_SETUP.md) (Rust, WebAssembly
+target, Stellar CLI, Node.js 22, Git). The guide includes verification steps
+to confirm your machine is ready.
+
+You should also have a basic understanding of Soroban smart contracts, Git, and GitHub.
+
+### Setup (Fork Workflow)
+
+To set up a local development environment, follow this fork-and-clone workflow:
+
+1. **Fork the Repository**: Visit [Notify-Chain](https://github.com/Core-Foundry/Notify-Chain) and click the **Fork** button to create a copy of the repository under your GitHub account.
+2. **Clone your Fork**:
+   ```bash
+   git clone https://github.com/your-username/Notify-Chain.git
+   cd Notify-Chain
+   ```
+3. **Configure Upstream Remote**: Keep your fork updated by pointing to the upstream repository:
+   ```bash
+   git remote add upstream https://github.com/Core-Foundry/Notify-Chain.git
+   ```
+4. **Verify Remotes**: Run `git remote -v` to ensure your configuration is correct:
+   ```bash
+   origin    https://github.com/your-username/Notify-Chain.git (fetch)
+   origin    https://github.com/your-username/Notify-Chain.git (push)
+   upstream  https://github.com/Core-Foundry/Notify-Chain.git (fetch)
+   upstream  https://github.com/Core-Foundry/Notify-Chain.git (push)
+   ```
+
+### Syncing Your Fork
+
+Before starting any new work or creating a branch, always pull the latest changes from the upstream `main` branch to prevent merge conflicts:
 - Give constructive, specific feedback
 - Show empathy — everyone is learning
 

CONTRIBUTOR_SETUP.md

@@ -1,5 +1,14 @@
 # Contributor Environment Setup Guide
 
+> **Canonical setup guide:** [`docs/ENVIRONMENT_SETUP.md`](docs/ENVIRONMENT_SETUP.md)
+
+That document contains step-by-step instructions to install required tools,
+clone the repository, configure the listener and dashboard, build contracts, and
+verify your installation (including CI-parity checks).
+
+For day-to-day development after setup, see [LOCAL_DEVELOPMENT.md](LOCAL_DEVELOPMENT.md).
+For Git workflow (fork, branch, PR), see
+[CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md](CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md).
 > Goal: a new contributor should be able to set up NotifyChain from scratch on a clean machine without asking maintainers for help.
 
 ---

docs/ENVIRONMENT_SETUP.md

@@ -0,0 +1,236 @@
+# Contributor Environment Setup
+
+Step-by-step instructions to set up NotifyChain on a clean machine. When you
+finish the [verification checklist](#verification-checklist), contracts build,
+the listener responds on its health endpoint, and component tests run the same
+commands as [CI](../.github/workflows/ci.yml).
+
+Related guides (deeper detail, not required for first setup):
+
+- [LOCAL_DEVELOPMENT.md](../LOCAL_DEVELOPMENT.md) — running the full stack day to day
+- [CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md](../CONTRIBUTOR_DEVELOPMENT_WORKFLOW_GUIDE.md) — fork, branch, and PR workflow
+- [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) — common errors
+
+---
+
+## 1. Required tools
+
+| Tool | Version (CI) | Purpose |
+|------|----------------|---------|
+| Git | 2.30+ | Clone and contribute |
+| Rust (stable) | stable | Soroban smart contracts |
+| `wasm32-unknown-unknown` | — | Contract WASM target |
+| Stellar CLI | latest | Build and deploy contracts |
+| Node.js | **22** | Listener and dashboard (see `.github/workflows/ci.yml`) |
+| npm | bundled with Node | Install dependencies |
+
+### Install Rust, WASM target, and Stellar CLI
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source "$HOME/.cargo/env"
+rustup target add wasm32-unknown-unknown
+cargo install --locked stellar-cli --features opt
+```
+
+### Install Node.js 22
+
+Use [nodejs.org](https://nodejs.org/) or [nvm](https://github.com/nvm-sh/nvm):
+
+```bash
+nvm install 22
+nvm use 22
+```
+
+### Verify installations
+
+```bash
+git --version
+rustc --version && cargo --version
+stellar --version
+node --version   # expect v22.x in CI
+npm --version
+```
+
+All commands above should print a version without errors.
+
+---
+
+## 2. Clone the repository
+
+For contributions, fork [Core-Foundry/Notify-Chain](https://github.com/Core-Foundry/Notify-Chain) on GitHub, then:
+
+```bash
+git clone https://github.com/YOUR-USERNAME/Notify-Chain.git
+cd Notify-Chain
+git remote add upstream https://github.com/Core-Foundry/Notify-Chain.git
+git fetch upstream
+git checkout main
+git merge upstream/main
+```
+
+Read-only clone (no fork):
+
+```bash
+git clone https://github.com/Core-Foundry/Notify-Chain.git
+cd Notify-Chain
+```
+
+---
+
+## 3. Listener service
+
+The listener polls Stellar, processes events, and exposes the events HTTP API.
+
+```bash
+cd listener
+npm ci
+cp .env.example .env
+```
+
+Edit `listener/.env`. Minimum for local development:
+
+```bash
+STELLAR_RPC_URL=https://soroban-testnet.stellar.org:443
+CONTRACT_ADDRESSES=[{"address":"YOUR_CONTRACT_ID","events":["*"]}]
+```
+
+Initialize the database and start the service:
+
+```bash
+npm run migrate
+npm run dev
+```
+
+In another terminal, confirm the service is up:
+
+```bash
+curl -s http://localhost:8787/health
+curl -s http://localhost:8787/api/events
+```
+
+---
+
+## 4. Dashboard
+
+```bash
+cd dashboard
+npm ci
+```
+
+Optional: create `dashboard/.env` if the listener is not on the default URL:
+
+```bash
+# Example — adjust port if EVENTS_API_PORT differs in listener/.env
+VITE_EVENTS_API_URL=http://localhost:8787
+```
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173). The UI should load without CORS errors when the listener is running.
+
+---
+
+## 5. Smart contracts
+
+### AutoShare (`contract/`)
+
+```bash
+cd contract
+stellar contract build
+cd contracts/hello-world
+cargo test
+```
+
+### TaskBounty (`Documents/Task Bounty/`)
+
+```bash
+cd "Documents/Task Bounty"
+stellar contract build
+cargo test
+```
+
+---
+
+## 6. Optional: frontend analytics app
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) when you work on analytics UI.
+
+---
+
+## 7. Environment variables
+
+- Listener: see `listener/.env.example` and [ENVIRONMENT_VARIABLES_AND_SECRETS.md](../ENVIRONMENT_VARIABLES_AND_SECRETS.md)
+- Dashboard: `VITE_EVENTS_API_URL` (events API base URL)
+
+---
+
+## Verification checklist
+
+Complete these steps to confirm your environment is ready for development.
+
+### Toolchain
+
+- [ ] `rustc`, `cargo`, `stellar`, `node`, and `npm` versions print successfully
+- [ ] `rustup target list --installed` includes `wasm32-unknown-unknown`
+
+### Listener
+
+- [ ] `cd listener && npm ci` completes without errors
+- [ ] `npm run migrate` creates `listener/data/notifications.db`
+- [ ] `npm run dev` starts without crashing
+- [ ] `curl http://localhost:8787/health` returns HTTP 200 with `"status":"ok"`
+
+### Dashboard
+
+- [ ] `cd dashboard && npm ci` completes
+- [ ] `npm run dev` serves the app on port 5173
+- [ ] Browser loads the dashboard with the listener running
+
+### Contracts
+
+- [ ] `stellar contract build` succeeds under `contract/`
+- [ ] `cargo test` passes in `contract/contracts/hello-world` (when the workspace builds)
+- [ ] `cargo test` passes under `Documents/Task Bounty/`
+
+### CI parity (run before opening a PR)
+
+```bash
+# Listener
+cd listener && npm ci && npm run lint && npm run typecheck && npm test --silent
+
+# Dashboard
+cd dashboard && npm ci && npm run lint && npm run build && npm test --silent && npm run test:wallet --silent
+
+# Contracts
+cd contract && cargo fmt --all -- --check && cargo test --workspace --all-features --verbose
+```
+
+- [ ] All commands above succeed on your machine (or note pre-existing upstream failures in your PR)
+
+---
+
+## 8. VS Code (recommended)
+
+Install [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) and [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint). The repo includes `.vscode/settings.json` with `wasm32-unknown-unknown` configured for contracts.
+
+---
+
+## 9. Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `sqlite3` / `node-gyp` install errors | `npm rebuild sqlite3`; install platform build tools (see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md)) |
+| `SQLITE_ERROR: no such table` | `cd listener && npm run migrate` |
+| Dashboard cannot reach API | Match `VITE_EVENTS_API_URL` to listener `EVENTS_API_PORT` |
+| Port 8787 in use | Change `EVENTS_API_PORT` in `listener/.env` or stop the conflicting process |
+
+For more detail, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md).