From 05208d3ac2d259736d411f09eb15d7f91d8100d7 Mon Sep 17 00:00:00 2001 From: Rudues Date: Mon, 31 Aug 2026 11:50:50 +0000 Subject: [PATCH 1/4] docs(security): add SECURITY.md with vulnerability disclosure policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add private reporting channels (GitHub Security Advisories, email) - Define response SLA: acknowledge within 5 business days - Explicitly scope high-priority security areas: signature verification, fund-moving code, solver registry, WebSocket auth - Cross-reference existing security tracking issues (#19, #20, #26, #82–#97, #96) - Document out-of-scope categories and best practices - Link to related governance documentation Closes #312 --- SECURITY.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..81533c3 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,97 @@ +# Security Policy + +## Supported Versions + +The project currently supports the `main` branch only. Security patches and bug fixes are deployed to production as they are completed. Stable releases have not yet been established. + +## Reporting a Vulnerability + +We take security seriously. If you discover a security vulnerability, please **do not open a public GitHub issue**. Instead, report it privately through GitHub's Security Advisory feature or by emailing security@vortex-protocol.dev. + +### Private Reporting Channels + +1. **GitHub Security Advisories** (Preferred) + - Navigate to the repository's Security tab + - Click "Report a vulnerability" to open a private advisory + - This is the fastest and most secure way to notify us + +2. **Email** + - Send a detailed report to: security@vortex-protocol.dev + - Please include: + - A clear description of the vulnerability + - Steps to reproduce (if applicable) + - Potential impact and severity assessment + - Any suggested fixes + +### Response Timeline + +- **Acknowledgment**: We will acknowledge receipt of your report within **5 business days** +- **Investigation**: We will investigate and provide an initial assessment within **10 business days** +- **Remediation**: Our goal is to have a patch or mitigation plan within **30 days** for critical issues +- **Disclosure**: We will coordinate with you on a responsible disclosure timeline + +For active security issues with high severity, we may expedite this process. + +## Security Scope + +The following components are explicitly in scope for security research and vulnerability reports: + +### High-Priority Security Areas + +- **Signature & Authentication** (`src/common/stellar-signature.ts`, `src/soroban/signer.service.ts`) + - Ed25519 signature verification on state-mutating endpoints + - Signing key management and validation + - Known tracking issues: #19, #20, #26 + +- **Fund-Moving Code** (`src/soroban/stellar-tx.service.ts`) + - Transaction construction and submission logic + - Settlement contract integration + - Known tracking issues: #82–#97 + +- **Solver Registry & Authorization** (related to issues #82–#97) + - Access control for solver operations + - Bond management and verification + +- **WebSocket & Real-Time Updates** (related to issue #96) + - Authentication of WebSocket connections + - Rate limiting and resource exhaustion protections + +### Known Security Tracking Issues + +Reporters are encouraged to review the existing issue tracker to avoid duplicate reports: + +- **Authentication & Verification**: #19, #20, #26 +- **Contract & Transaction Security**: #82–#97 +- **Real-Time Communication**: #96 + +If your finding relates to one of these tracked issues, please specify which one in your report. + +## Out of Scope + +The following are not in scope for security vulnerability reports: + +- Configuration errors on production deployments +- Missing security headers in default environments (our defaults follow best practices; issues with custom deployments should be reported to the operator) +- Performance or availability issues unrelated to intentional resource-exhaustion protections +- Third-party dependency vulnerabilities (please report directly to the maintainer of that package; we will update dependencies as patches are released) + +## Security Best Practices + +Contributors are expected to: + +- Never commit secrets (API keys, signing keys, private credentials) to the repository +- Use `SOROBAN_SIGNING_KEY` from `.env` only (it is validated against Stellar secret seed format at startup in production) +- Review `.env.mainnet.example` and `.env.testnet.example` for secure configuration patterns +- Run `npm audit` locally before opening a PR +- Ensure Gitleaks secrets scanning passes in CI + +## Related Documentation + +- [CONTRIBUTING.md](./CONTRIBUTING.md) — Backend development conventions +- [CODE_OF_CONDUCT.md](https://github.com/vortex-protocol/.github/blob/main/CODE_OF_CONDUCT.md) — Community code of conduct +- `.github/workflows/ci.yml` — CI pipeline including secrets scanning (`secrets-scan`) and audit checks (`npm audit`) +- `commitlint.config.js` — Enforced commit message standards + +## Maintenance + +This security policy will be reviewed and updated as the project evolves. Critical security findings may trigger policy updates; changes will be reflected in future releases. From feccbfa5bae30200ac8bebeadf68b0b20fd5eca0 Mon Sep 17 00:00:00 2001 From: Rudues Date: Mon, 31 Aug 2026 11:52:15 +0000 Subject: [PATCH 2/4] docs(labels): define label taxonomy and issue management process - Create docs/LABEL_TAXONOMY.md with difficulty and category labels - Define mapping rules for mirroring issues.md entries to GitHub Issues - Include exclusion rules (blockers, cross-module refactoring) - Document status labels for tracking lifecycle - Add label reference to CONTRIBUTING.md - Establish maintenance process for label consistency Closes #313 --- CONTRIBUTING.md | 25 +++++++++++++- docs/LABEL_TAXONOMY.md | 77 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 1 deletion(-) create mode 100644 docs/LABEL_TAXONOMY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80b6391..210f93a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,8 @@ Closes #135 8. [Environment variables](#environment-variables) 9. [Regenerating the API client SDK](#regenerating-the-api-client-sdk) 10. [Commit messages](#commit-messages) -11. [Submitting a pull request](#submitting-a-pull-request) +11. [GitHub issue labels](#github-issue-labels) +12. [Submitting a pull request](#submitting-a-pull-request) --- @@ -341,6 +342,28 @@ entry. --- +## GitHub issue labels + +When creating or triaging GitHub Issues, use the label taxonomy defined in +[docs/LABEL_TAXONOMY.md](./docs/LABEL_TAXONOMY.md) to categorize work by difficulty +and area. This helps contributors discover work that matches their skill level and +interest. + +### Quick reference + +- **`good-first-issue`** — Suitable for newcomers; isolated, self-contained, no major + prerequisites blocking +- **`help-wanted`** — Open to anyone; clear scope but could benefit from fresh eyes +- **`category/*`** — Categorize by area: `category/backend`, `category/security`, + `category/devops`, `category/governance` +- **`status/*`** — Track lifecycle: `status/in-progress`, `status/blocked`, + `status/ready-to-merge` + +For detailed mapping rules (e.g. how to label issues from the contributor backlog), +see [docs/LABEL_TAXONOMY.md](./docs/LABEL_TAXONOMY.md). + +--- + ## Submitting a pull request 1. Fork the repo and create a feature branch from `main`: diff --git a/docs/LABEL_TAXONOMY.md b/docs/LABEL_TAXONOMY.md new file mode 100644 index 0000000..395a7a8 --- /dev/null +++ b/docs/LABEL_TAXONOMY.md @@ -0,0 +1,77 @@ +# Label Taxonomy and Issue Management + +## Overview + +This document defines the label taxonomy for GitHub Issues, used to categorize contributor work from `issues.md` and help new contributors discover work that matches their skill level. + +## Label Categories + +### Difficulty Labels + +Used to indicate the expected difficulty and prerequisite knowledge for a given issue. + +| Label | Color | Description | Candidates | +|-------|-------|-------------|-----------| +| `good-first-issue` | `#7057ff` | Suitable for newcomers with no major prerequisites; isolated, self-contained scope | Medium complexity issues with no unresolved High-complexity prerequisites | +| `help-wanted` | `#008672` | Open to anyone; may have a clear scope but could benefit from fresh eyes or bandwidth | Any complexity level without critical-path blocking | +| `hard` | `#d73a49` | Significant challenge; may require deep codebase knowledge or non-trivial design work | High complexity issues; new architectural patterns | + +### Category Labels + +Mirror the four implicit categories in `issues.md`: + +| Label | Color | Description | +|-------|-------|-------------| +| `category/backend` | `#c2e0c6` | Backend API, services, database, integrations | +| `category/security` | `#fc2929` | Security audit, vulnerability disclosure, authentication | +| `category/devops` | `#1d76db` | Infrastructure, CI/CD, monitoring, operations | +| `category/governance` | `#ffc274` | Community, documentation, process, contributor onboarding | + +### Status Labels + +Track issue lifecycle: + +| Label | Color | Description | +|-------|-------|-------------| +| `status/blocked` | `#d73a49` | Cannot proceed; describes blocker in the issue or comment | +| `status/in-progress` | `#0075ca` | Being actively worked on; PR referenced in issue or comment | +| `status/ready-to-merge` | `#a2eeef` | Approved PR awaiting merge; linked PR should reference issue number | + +## Mapping Rules + +### From `issues.md` to GitHub Issues + +When mirroring an issue from `issues.md` to GitHub: + +1. **Title**: Use the issue's `[DESCRIPTION]` line verbatim +2. **Body**: Include the full `[DESCRIPTION]` + `[PROBLEM STATEMENT & CONTEXT]` sections; link back to `issues.md` +3. **Category Label**: Determine from the issue's category in `issues.md`; apply one of `category/backend`, `category/security`, `category/devops`, or `category/governance` +4. **Difficulty Label**: Apply based on Complexity + prerequisites: + - **`good-first-issue`**: If Complexity is `Medium` AND the issue description does not reference any High-complexity issue numbers as prerequisites + - **`help-wanted`**: If the issue is open and not currently assigned, and is not blocked by another open issue + - **`hard`**: If Complexity is `High`, always apply (in addition to category label) +5. **Prerequisites**: In the issue body, add a "Prerequisites" section listing any dependent issues (those referenced in Implementation Guidelines or Problem Statement) + +**Example**: Issue #25 in `issues.md` is "Medium" complexity in Backend, doesn't reference a High blocker → `category/backend` + `good-first-issue` + +### Exclusion Rules + +Do **not** mark an issue as `good-first-issue` if: +- Any of its prerequisites are still open +- It requires significant cross-module refactoring +- Its description includes "TODO: [document the unfinished design]" or similar + +## Maintenance + +- When an issue is closed (PR merged), remove the `help-wanted` label if present +- When an issue moves to active work, add `status/in-progress` and reference the PR +- When a PR is approved, add `status/ready-to-merge` (removed on merge) +- Review labels quarterly as the backlog evolves + +## Initial Seed Batch + +The first batch of issues mirrored from `issues.md` (issues #316–#330) should include examples from all categories and both difficulty levels to establish a clear pattern for future contributors. + +--- + +For more context on how the contributor backlog is managed, see [CONTRIBUTING.md](./CONTRIBUTING.md) and [issues.md](./issues.md) in the upstream repository. From 573aae83bea807cd6da194c898a75b4f3c8607bd Mon Sep 17 00:00:00 2001 From: Rudues Date: Mon, 31 Aug 2026 11:52:59 +0000 Subject: [PATCH 3/4] docs(changelog): document changelog update process and Conventional Commits mapping - Update CHANGELOG.md with detailed instructions on how to update entries - Document mapping from Conventional Commit types to changelog sections - Add changelog update section to CONTRIBUTING.md with examples - Clarify that chore and test commits skip changelog (no user-visible change) - Reference Keep a Changelog and Conventional Commits standards Closes #314 --- CHANGELOG.md | 18 +++++++++++++++--- CONTRIBUTING.md | 18 ++++++++++++++++++ 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 599b189..c890311 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,21 @@ and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) conventions. Commit message format is enforced via [commitlint](https://commitlint.js.org/) starting with v0.2.0. > **How to update this file** -> Run `npm run generate:client` after any API surface change and bump the version -> in `package.json`. Add your changes under `[Unreleased]` as you work; entries -> are moved to a versioned section on release. +> +> Add entries to the `[Unreleased]` section as you work on features and fixes. +> Organize by subsection (`Added`, `Fixed`, `Removed`, etc.) as defined below. +> +> **Mapping from Conventional Commits:** +> - `feat(scope): ...` → `[Added]` +> - `fix(scope): ...` → `[Fixed]` +> - `perf(scope): ...` → `[Changed]` (with note about performance improvement) +> - `refactor(scope): ...` → `[Changed]` (with scope of refactoring) +> - `docs(scope): ...` → `[Documentation]` (if user-facing; skip if internal only) +> - `chore(scope): ...` → Skip (internal tooling, no user-visible change) +> +> On version release, the `[Unreleased]` section is renamed to `[X.Y.Z]` with the +> release date, and a new `[Unreleased]` section is created. Version must be bumped +> in `package.json` to match. --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 210f93a..256fa95 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -340,6 +340,24 @@ The CI job `commitlint` checks the PR title on every pull request. Squash merges are preferred so that the merge commit title is the canonical changelog entry. +### Updating the changelog + +When working on a feature or fix that affects users, add an entry to `CHANGELOG.md` +under `[Unreleased]` before opening your PR: + +| Commit Type | Changelog Section | Example | +|-------------|-------------------|---------| +| `feat(...)` | `Added` | A new endpoint or behavior | +| `fix(...)` | `Fixed` | A bug fix or behavioral correction | +| `perf(...)` | `Changed` | Performance improvement | +| `refactor(...)` | `Changed` | Major structural change affecting users | +| `docs(...)` | `Documentation` | User-facing documentation changes | +| `chore(...)` | — | Skip (internal tooling, no user-visible change) | +| `test(...)` | — | Skip (internal tests, no user-visible change) | + +For details on changelog format and section definitions, see the instructions in +`CHANGELOG.md`. + --- ## GitHub issue labels From 0f134d3294b070b98e581bb08452bab1bec9ff21 Mon Sep 17 00:00:00 2001 From: Rudues Date: Mon, 31 Aug 2026 11:53:50 +0000 Subject: [PATCH 4/4] docs(governance): add Drips Wave contributor accounting ledger and process MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create docs/DRIPS_WAVE_LEDGER.md with ledger table and accounting rules - Define point values (200 for High complexity, 150 for Medium) - Document source-of-truth mechanism: Closes tag in PR description - Establish dispute resolution process referencing CODE_OF_CONDUCT.md - Add Drips Wave section to CONTRIBUTING.md with contributor workflow - Enable auditable tracking of issue number → contributor → points Closes #315 --- CONTRIBUTING.md | 35 +++++++++++++++++++++ docs/DRIPS_WAVE_LEDGER.md | 65 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 docs/DRIPS_WAVE_LEDGER.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 256fa95..e1d19cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -380,6 +380,41 @@ interest. For detailed mapping rules (e.g. how to label issues from the contributor backlog), see [docs/LABEL_TAXONOMY.md](./docs/LABEL_TAXONOMY.md). +## Drips Wave contributor accounting + +This project offers a points-based contributor incentive program (Drips Wave). +Contributors who close issues earn points that are recorded in a ledger. + +### How points are awarded + +Every issue in the contributor backlog has a fixed point value: +- **High complexity**: 200 points +- **Medium complexity**: 150 points + +When your PR closes an issue, the points for that issue are credited to your contributor account. +See [docs/DRIPS_WAVE_LEDGER.md](./docs/DRIPS_WAVE_LEDGER.md) for the full ledger and accounting rules. + +### For PR authors + +When you open a PR that solves an issue from the backlog, include a `Closes` tag in your +PR description to link the PR to the issue number: + +```markdown +## Description + +Brief description of the changes. + +Closes # +``` + +This creates an auditable record that ties your PR to a specific point value. The ledger +is updated when the PR is merged. + +### Disputes and escalation + +If there's a disagreement about points, attribution, or the ledger record, see the +escalation process in [docs/DRIPS_WAVE_LEDGER.md](./docs/DRIPS_WAVE_LEDGER.md). + --- ## Submitting a pull request diff --git a/docs/DRIPS_WAVE_LEDGER.md b/docs/DRIPS_WAVE_LEDGER.md new file mode 100644 index 0000000..5520d16 --- /dev/null +++ b/docs/DRIPS_WAVE_LEDGER.md @@ -0,0 +1,65 @@ +# Drips Wave Contributor Ledger + +This document records contributions to the vortex-backend contributor incentive program (Drips Wave), tracking issue numbers, contributors, merge dates, and points awarded. + +## Format + +| Merge Date | PR | Contributor | Issue Number | Issue Title | Points | Notes | +|------------|-----|-------------|--------------|-------------|--------|-------| +| YYYY-MM-DD | #XXX | @username | #N | Short description | 150/200 | Any special context | + +## Ledger + +### Phase 1 (Q3 2026) + +_(Initial seed batch — to be populated as first wave of issues are completed)_ + +## Accounting Rules + +### Point Values + +- **High complexity**: 200 points +- **Medium complexity**: 150 points + +Complexity levels are defined in `issues.md` (upstream) and referenced in GitHub Issue descriptions. + +### Source of Truth + +Each PR must reference an issue number in its description: +``` +Closes # +``` + +This creates a verifiable link between the merged PR and the `issues.md` entry, enabling automated or manual ledger updates. + +### Recording Process + +1. **PR opens**: Author ensures the description includes `Closes #` +2. **PR merged**: Merge commit title captures the change; the linked issue is the join key +3. **Ledger update**: A maintainer (or automated CI job, if implemented) adds a row to this ledger + +The ledger is append-only; rows are not deleted or modified once recorded. + +### Dispute Resolution + +Disputes about point allocation or contributor attribution follow the escalation ladder in +[CODE_OF_CONDUCT.md](https://github.com/vortex-protocol/.github/blob/main/CODE_OF_CONDUCT.md): + +1. **Clarification**: Poster of ledger entry and contributor agree on facts +2. **Maintainer review**: If disagreement persists, a maintainer with push access reviews the issue and PR +3. **Escalation**: Unresolved disputes are brought to the team lead for final decision + +Changes to the ledger (if any are needed) are documented in a follow-up commit with reasoning. + +## Notes + +- This ledger is not a replacement for contributor recognition elsewhere (e.g. GitHub's contributor graph, release notes) +- Point totals do not automatically convert to payments or rewards; that is handled separately and outside this repository +- Ledger entries are public and auditable; disputes and resolutions are also documented publicly + +--- + +For more context on the Drips Wave program, see: +- `issues.md` (upstream, in vortex-protocol/.github) — defines issues and point values +- [CONTRIBUTING.md](./CONTRIBUTING.md) — contributor workflow +- `CHANGELOG.md` — user-facing changes