diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..a9c5690 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,88 @@ +name: Bug report +description: Report a reproducible frontend, backend, contract, or CI problem. +title: "[Bug]: " +labels: + - bug + - dx +body: + - type: markdown + attributes: + value: | + Thanks for reporting a SecureFlow bug. Do not include secrets, private keys, API keys, or sensitive wallet data. + + - type: textarea + id: summary + attributes: + label: Summary + description: What happened, and what did you expect instead? + placeholder: I expected ..., but ... + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Reproduction steps + description: Provide the smallest set of steps or commands that reproduces the problem. + placeholder: | + 1. Run ... + 2. Open ... + 3. See ... + validations: + required: true + + - type: dropdown + id: area + attributes: + label: Affected layer + multiple: true + options: + - Frontend + - Backend + - Soroban contract + - Generated contract clients + - CI / tooling + - Documentation + - Not sure + validations: + required: true + + - type: input + id: os + attributes: + label: Operating system + placeholder: "macOS 15.5, Ubuntu 24.04, Windows 11, etc." + validations: + required: true + + - type: input + id: node-version + attributes: + label: Node.js version + placeholder: "node --version" + + - type: input + id: rust-version + attributes: + label: Rust version + placeholder: "rustc --version" + + - type: input + id: stellar-version + attributes: + label: Stellar CLI / scaffold version + placeholder: "stellar --version; stellar-scaffold --version" + + - type: textarea + id: logs + attributes: + label: Logs, screenshots, or failing output + description: Paste terminal output, browser console errors, screenshots, or test failures. Redact secrets. + render: shell + + - type: textarea + id: extra + attributes: + label: Additional context + description: Link related issues, PRs, deployments, or docs. + diff --git a/.github/ISSUE_TEMPLATE/contract_issue.yml b/.github/ISSUE_TEMPLATE/contract_issue.yml new file mode 100644 index 0000000..6a7ecee --- /dev/null +++ b/.github/ISSUE_TEMPLATE/contract_issue.yml @@ -0,0 +1,56 @@ +name: Contract issue +description: Report or propose a Soroban contract change. +title: "[Contract]: " +labels: + - contract + - security +body: + - type: markdown + attributes: + value: | + Use this for public contract bugs, invariants, gas issues, tests, or API concerns. For exploitable vulnerabilities, follow SECURITY.md and use a private advisory instead. + + - type: textarea + id: summary + attributes: + label: Summary + description: Describe the contract behavior, invariant, or API concern. + validations: + required: true + + - type: input + id: function + attributes: + label: Affected function or module + placeholder: "contracts/secureflow/src/... or function_name()" + validations: + required: true + + - type: textarea + id: impact + attributes: + label: Security implications + description: Explain possible effects on escrow funds, milestones, disputes, deadlines, permissions, storage, events, generated clients, or gas usage. + placeholder: "Impact is limited to ... / Could affect ..." + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Reproduction or test case + description: Include a failing test, command, transaction flow, or minimal scenario when possible. + render: shell + + - type: textarea + id: proposed-fix + attributes: + label: Proposed fix + description: Share the expected contract behavior or implementation direction. + + - type: textarea + id: references + attributes: + label: References + description: Link related docs, issues, PRs, audits, or Stellar/Soroban references. + diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..289bef7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,67 @@ +name: Feature request +description: Suggest a scoped SecureFlow improvement. +title: "[Feature]: " +labels: + - enhancement + - dx +body: + - type: markdown + attributes: + value: | + Use this for product, UX, frontend, backend, contract, testing, tooling, and documentation improvements. + + - type: textarea + id: problem + attributes: + label: Problem or opportunity + description: What user, contributor, operator, or maintainer problem should this solve? + placeholder: This would help because ... + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the change you would like to see. + placeholder: | + - Add ... + - Update ... + - Keep ... + validations: + required: true + + - type: dropdown + id: area + attributes: + label: Affected layer + multiple: true + options: + - Frontend + - Backend + - Soroban contract + - Generated contract clients + - CI / tooling + - Documentation + - Not sure + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Share workarounds, rejected approaches, or related designs. + + - type: textarea + id: testing + attributes: + label: Test or validation plan + description: What would prove this change works? + + - type: textarea + id: references + attributes: + label: References + description: Link related issues, PRs, docs, mockups, or external references. + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..2e6f109 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,47 @@ +## Why + + + +## What changed + +- + +## Type of change + +- [ ] feat +- [ ] fix +- [ ] docs +- [ ] test +- [ ] refactor +- [ ] chore / ci +- [ ] contract +- [ ] frontend +- [ ] backend + +## Test evidence + + + +- [ ] `npm run lint` +- [ ] `npx prettier . --check` +- [ ] `npm run build` +- [ ] `npm test --if-present` +- [ ] `cd backend && npm run build` +- [ ] `cargo fmt --all -- --check` +- [ ] `cargo clippy --workspace --all-targets -- -D warnings` +- [ ] `cargo test --workspace --locked` +- [ ] `STELLAR_SCAFFOLD_ENV=development stellar-scaffold build --build-clients` +- [ ] `npm run install:contracts` + +## Contract impact + +- [ ] No contract changes +- [ ] Affected functions/modules are listed +- [ ] Events, storage layout, generated clients, and security implications are documented + +## Safety checklist + +- [ ] No secrets, `.env` files, private keys, generated credentials, or build artifacts are committed +- [ ] User-visible behavior, API changes, or environment variable changes are documented +- [ ] Follow-up work is explicitly listed + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e015aa..19acfba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,182 @@ -# Contributing +# Contributing to SecureFlow -This is a guide to contributing to `scaffold-stellar-frontend` itself. Feel free to delete or modify it for your own project. +Thanks for helping improve SecureFlow. This guide should take you from a clean machine to a pull request without needing maintainer follow-up. + +## Prerequisites + +Install the core toolchain: + +```bash +# Node.js 20+ and npm +node --version +npm --version + +# Rust toolchain +rustup update +rustup target add wasm32v1-none + +# Stellar CLI and scaffold tooling +cargo install --locked stellar-cli +cargo install --locked stellar-scaffold-cli + +# Docker is required for the local Stellar quickstart network +docker --version +``` + +On Linux CI-like environments, install native packages used by Stellar dependencies: + +```bash +sudo apt-get update +sudo apt-get install -y libudev-dev libdbus-1-dev pkg-config +``` + +## Local setup + +Clone and install the frontend workspace: + +```bash +git clone https://github.com/Secureflow-protocol/secureflow.git +cd secureflow +npm install +``` + +Create local environment files: + +```bash +touch .env backend/.env +``` + +Frontend `.env`: + +```env +VITE_STELLAR_NETWORK=local +VITE_SECUREFLOW_CONTRACT_ID= +VITE_OWNER_ADDRESS= +VITE_API_URL=http://localhost:3001 +``` + +Backend `backend/.env`: + +```env +SUPABASE_URL= +SUPABASE_SERVICE_KEY= +GROQ_API_KEY= +PORT=3001 +``` + +Never commit real secrets, private keys, API keys, generated deployment credentials, or `.env` files. + +## Running the app + +Start a local Stellar network in one terminal: + +```bash +docker run --rm -p 8000:8000 stellar/quickstart:testing --local +``` + +Build the Soroban contracts and generated TypeScript clients: + +```bash +STELLAR_SCAFFOLD_ENV=development stellar-scaffold build --build-clients +npm run install:contracts +``` + +Start the frontend: + +```bash +npm run dev +``` + +Open `http://localhost:5173`. + +Start the backend in a separate terminal when testing API-backed flows: + +```bash +cd backend +npm install +npm run dev +``` + +## Test and quality checks + +Run the checks that match the layer you touched. Before opening a PR, run the full relevant set and paste the output or a short summary in the PR body. + +Frontend: + +```bash +npm run lint +npx prettier . --check +npm run build +npm test --if-present +``` + +Backend: + +```bash +cd backend +npm install +npm run build +``` + +Contracts: + +```bash +cargo fmt --all -- --check +cargo clippy --workspace --all-targets -- -D warnings +cargo test --workspace --locked +STELLAR_SCAFFOLD_ENV=development stellar-scaffold build --build-clients +npm run install:contracts +``` + +CI currently runs `npm ci`, `npm run lint`, `npx prettier . --check`, `stellar-scaffold build --build-clients`, `npm run install:contracts`, `npm run build`, and `npm test --if-present`. + +## Code style + +- Keep TypeScript typed and explicit around wallet, contract, and backend API boundaries. +- Use ESLint and Prettier for frontend and shared TypeScript changes. +- Use `cargo fmt` and `cargo clippy` for Rust/Soroban changes. +- Keep generated contract clients in sync with contract changes. +- Add tests for behavior changes. Do not delete or weaken tests without explaining why in the PR. +- Keep security-sensitive code small, auditable, and explicit. Avoid hidden fallbacks around wallet signing, escrow state, dispute resolution, and relayer behavior. + +## Commit style + +Use Conventional Commits: + +```text +type(scope): short imperative summary +``` + +Common types: + +- `feat`: user-visible feature +- `fix`: bug fix +- `docs`: documentation-only change +- `test`: tests or fixtures +- `refactor`: no behavior change +- `chore`: maintenance +- `ci`: GitHub Actions or release automation + +Examples: + +```text +docs(contributing): add setup guide and PR checklist +fix(contract): validate milestone index before payout +test(backend): cover relay request validation +``` + +## Pull request checklist + +Before requesting review: + +- [ ] The PR explains why the change is needed, not only what changed. +- [ ] Related issues are linked with `Closes #...` when applicable. +- [ ] Tests were added or updated for behavior changes. +- [ ] Relevant lint, format, build, and test commands pass, or the PR explains why they were not run. +- [ ] Contract changes document affected functions, events, storage, generated clients, and security implications. +- [ ] Frontend or backend changes document environment variables, API contracts, and user-visible behavior. +- [ ] No secrets, `.env` files, private keys, build artifacts, or generated credentials are committed. + +## Reporting issues + +Use the GitHub issue templates so maintainers get the affected layer, reproduction steps, environment details, and test evidence. Do not open public issues for vulnerabilities; follow `SECURITY.md` and use the private advisory flow.