From 3f8beb99f203e059c53a11b9b9879bd17db33293 Mon Sep 17 00:00:00 2001 From: lami111isah Date: Thu, 24 Sep 2026 16:25:35 +0000 Subject: [PATCH 1/4] feat(#306): Establish solver grievance and feedback process - Create dedicated solver-feedback GitHub issue template - Implement solver-feedback-process.md with documented triage cadence (7 days) - Define clear scope: feedback for operational concerns distinct from bug reports and slash appeals - Add escalation path to RFC process for potential governance proposals - Reference feedback process in solver-integration-guide.md for discoverability The process reuses existing GitHub tooling (labels/templates) and establishes a credible commitment to solver concerns through a documented review cadence. Edge cases for slash appeals, bug reports, and governance proposals are defined. --- .claude/settings.json | 20 +++ .github/ISSUE_TEMPLATE/solver-feedback.md | 56 +++++++ docs/solver-feedback-process.md | 189 ++++++++++++++++++++++ docs/solver-integration-guide.md | 19 +++ 4 files changed, 284 insertions(+) create mode 100644 .claude/settings.json create mode 100644 .github/ISSUE_TEMPLATE/solver-feedback.md create mode 100644 docs/solver-feedback-process.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..3c7ef49 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,20 @@ +{ + "permissions": { + "allow": [ + "Bash", + "Read", + "Edit", + "Write", + "WebFetch", + "Grep", + "Glob", + "LS", + "MultiEdit", + "NotebookRead", + "NotebookEdit", + "TodoRead", + "TodoWrite", + "WebSearch" + ] + } +} diff --git a/.github/ISSUE_TEMPLATE/solver-feedback.md b/.github/ISSUE_TEMPLATE/solver-feedback.md new file mode 100644 index 0000000..aede8ac --- /dev/null +++ b/.github/ISSUE_TEMPLATE/solver-feedback.md @@ -0,0 +1,56 @@ +--- +name: Solver Feedback +about: Raise operational concerns about the protocol (distinct from bug reports and slash appeals) +title: '[Solver Feedback] ' +labels: solver-feedback +--- + +# Solver Operational Feedback + +Thank you for taking the time to share your operational concerns or suggestions with the Vortex Protocol community. + +**Note:** This channel is for operational feedback, insights, and concerns from solvers navigating the protocol in production or on testnet. It is explicitly **not** for: +- Bug reports (use the "Bug Report" template instead) +- Formal slash-event appeals (see the [Slash Appeal Process](../docs/slash-appeal-process.md) instead) +- General protocol governance proposals (see the [RFC Process](../docs/rfc-process.md) for formal governance) + +--- + +## Concern Category + +What type of operational concern are you raising? + +- [ ] Fee or incentive structure +- [ ] Fill window or timing constraints +- [ ] Bond or collateral requirements +- [ ] Route or market coverage gaps +- [ ] Monitoring or observability limitations +- [ ] Other (please describe below) + +## Operational Context + +**Describe the operational constraint or concern:** + +[Provide specific details about what you've observed in your solver operations that prompted this feedback. Include testnet/mainnet context if applicable.] + +**Scale and Impact:** + +[How broadly does this affect solvers? Is this a niche issue for specific route types, or a systemic concern? Any quantitative impact data?] + +--- + +## Suggested Direction (Optional) + +If you have thoughts on how the protocol might better support your operational needs, share them here. This is input, not a binding proposal. + +[Suggestions and thoughts...] + +--- + +## Triage Notes + +*For protocol maintainers:* +- Triage target: within 7 calendar days of filing +- Response: acknowledging receipt and indicating whether this is being considered, escalated to the RFC process, or closed with rationale + +See [Solver Feedback Process](../docs/solver-feedback-process.md) for details. diff --git a/docs/solver-feedback-process.md b/docs/solver-feedback-process.md new file mode 100644 index 0000000..a0d5575 --- /dev/null +++ b/docs/solver-feedback-process.md @@ -0,0 +1,189 @@ +# Solver Feedback Process + +## Overview + +The Vortex Protocol depends on solvers as a first-class operational constituency. This document establishes a dedicated, lightweight feedback channel for solvers to raise concerns about the protocol's operational constraints, incentive structures, or market design—distinct from bug reports and distinct from the formal [Slash Appeal Process](./dispute-resolution-design.md). + +This channel is a **listening mechanism**, not a voting mechanism. Solver feedback informs protocol decisions and potential governance proposals (see the RFC process in [CONTRIBUTING.md](../CONTRIBUTING.md)), but does not automatically trigger changes. The goal is to make the channel a credible, responsive commitment: solvers know their operational concerns will be heard and considered, even if not all concerns result in protocol changes. + +--- + +## Scope + +### In Scope: Solver Feedback + +- **Operational constraints**: "The fill window is systematically too short for route X," "bond requirements disproportionately affect smaller solvers" +- **Market design concerns**: "Fee tiers don't account for Y external cost," "the incentive structure disadvantages solver type Z" +- **Observability gaps**: "I can't reliably monitor bond health across all my positions," "there's no way to detect collateral sufficiency trends" +- **Route or market coverage**: "There's a profitable route no solver currently serves; protocol design might explain why" +- **Real-world operational friction**: Any concern stemming from actually running a solver in production or testnet + +### Out of Scope: Slash Appeals & Governance + +- **Slash event appeals**: Use the [Slash Appeal Process](./dispute-resolution-design.md) for contesting a specific slashing incident +- **Bug reports**: Use the standard Bug Report template; solver feedback is not for bug triage +- **Formal governance proposals**: Use the RFC process (see [CONTRIBUTING.md](../CONTRIBUTING.md)) if your feedback has matured into a concrete proposal affecting protocol rules, contract behavior, or resource allocation + +--- + +## Process + +### 1. Filing Solver Feedback + +1. Open a new issue in [stellar-vortex-protocol/vortex-contracts](https://github.com/stellar-vortex-protocol/vortex-contracts). +2. Choose the **Solver Feedback** issue template. +3. Fill in: + - **Concern Category**: Select the type of operational issue (fee structure, timing, bond, route coverage, observability, other) + - **Operational Context**: Describe what you observed in production/testnet and why it matters + - **Scale and Impact**: Indicate whether this is a niche issue or systemic + - **Suggested Direction** (optional): Share any thoughts on how the protocol could adapt, but this is input, not a binding proposal + +4. Label the issue `solver-feedback`. + +### 2. Triage & Response + +**Triage window**: Solver feedback issues are triaged within **7 calendar days** of filing. + +**Triage response** includes: + +- **Acknowledgment**: Issue author receives a comment confirming receipt. +- **Initial categorization**: + - Is this a known operational constraint already documented (e.g., fill-window timing is specified in [solver-integration-guide.md](./solver-integration-guide.md))? + - Is this actionable feedback that might inform a governance proposal? + - Is this better handled as a bug report or formal governance request? + - Is this out-of-scope solver feedback (e.g., a slash appeal misrouted here)? +- **Next steps**: + - If actionable and in-scope: the issue remains open and tagged `solver-feedback` while the maintainers consider escalation to the RFC process or future protocol versions. + - If already documented/resolved: explain the existing design rationale and close with a reference to relevant docs. + - If this should be a formal governance proposal: suggest the RFC process and note how the feedback could feed into it. + - If out-of-scope: redirect to the appropriate process and close. + +### 3. Escalation to Governance + +If solver feedback identifies a concern that merits formal protocol change: + +1. Raise an RFC issue (see [CONTRIBUTING.md](../CONTRIBUTING.md)) that explicitly references the original solver feedback. +2. Link back from the original feedback issue to the RFC, so both form an audit trail. +3. The RFC process then follows the standard governance flow. + +### 4. Documenting Rationale + +If a piece of solver feedback is **not** escalated to governance (e.g., a concern about the fill window that is actually a designed constraint), the triage response documents why. This keeps the feedback channel honest: solvers see that their concerns are considered, even when the answer is "this is by design for reason X." + +--- + +## Review Cadence + +| Cadence | Responsibility | +|---------|---| +| **Triage**: Within 7 calendar days | Protocol maintainers | +| **Consideration & escalation decision**: Within 14 calendar days | Core team and governance group | +| **Monthly summary**: Optional | Maintainers share aggregated solver feedback themes in dev notes or governance updates | + +--- + +## Responsibilities + +### Solvers (Issue Filers) + +- Use this channel for operational concerns, not bug reports or governance proposals +- Be specific and concrete about the constraint you're encountering +- Indicate scale: is this affecting you alone, or a broader solver population? +- Be respectful; this is a listening channel, not a negotiation + +### Protocol Maintainers + +- Triage all solver-feedback issues within 7 days +- Explain design rationale when feedback reflects existing constraints +- Escalate to governance when feedback merits formal consideration +- Keep the channel responsive; a multi-week silence erodes the channel's credibility + +### Governance Group (Issue #117's process, once adopted) + +- Review solver-feedback issues during formal RFC discussions if escalated +- Factor solver operational insights into governance decisions +- Document how solver feedback influenced (or didn't) a final decision + +--- + +## Edge Cases + +### Case 1: Solver Feedback That Should Be a Slash Appeal + +**Scenario**: A solver files feedback that is actually about contesting a specific slash event. + +**Resolution**: Maintainer redirects to the [Slash Appeal Process](./dispute-resolution-design.md) and closes the feedback issue, explaining the distinction. + +### Case 2: Feedback About an Already-Open RFC or Governance Proposal + +**Scenario**: Solver feedback surfaces an operational concern that a current RFC is already addressing. + +**Resolution**: Link both issues together; the solver feedback becomes input to the ongoing RFC discussion rather than spawning a new parallel process. + +### Case 3: Systemic Feedback That Reveals a Design Gap + +**Scenario**: Multiple solvers independently report the same operational constraint (e.g., "fill window is too short for route X"). + +**Resolution**: Maintainers or governance participants can aggregate these issues, recognize a pattern, and escalate a single well-scoped RFC rather than leaving multiple disconnected feedback issues open. The aggregation is transparent (linked issues). + +### Case 4: Feedback With No Clear Resolution Path + +**Scenario**: A solver raises a legitimate concern (e.g., "smaller solvers feel disadvantaged") that is more of a long-term design question than a discrete protocol change. + +**Resolution**: Triage acknowledges the concern, documents that it's recognized but beyond the scope of near-term governance, and leaves it open as a standing concern for the community to revisit. Closing without resolution is worse than leaving it open to signal "we heard you, and this is a hard problem we're still thinking about." + +--- + +## Relationship to Other Processes + +### vs. Bug Reports + +- **Bug reports** are code defects, contract logic errors, or observability tools breaking unexpectedly. +- **Solver feedback** is operational concerns or constraints that may be working as designed. + +Use the Bug Report template if you've found a defect; use Solver Feedback if you're raising a concern about how the protocol's operational constraints affect your business. + +### vs. Slash Appeals + +- **Slash appeals** (see [dispute-resolution-design.md](./dispute-resolution-design.md)) contest a specific slash event: "I was slashed unfairly for reason X." +- **Solver feedback** is broader: "the protocol's design makes it hard to avoid slashing for scenario Y." + +If you were slashed and want to appeal, use the Slash Appeal process. If you want to raise a concern that affects multiple scenarios, use Solver Feedback. + +### vs. RFC / Governance Proposals + +- **Solver feedback** is input and listening: "here's what I'm observing operationally." +- **RFC proposals** (see [CONTRIBUTING.md](../CONTRIBUTING.md)) are concrete: "the protocol should change X because Y." + +Solver feedback can **feed into** an RFC, but filing feedback isn't the same as proposing a change. Once you have a concrete proposal, file an RFC. + +--- + +## Reference + +- [Solver Integration Guide](./solver-integration-guide.md) — operational constraints and integration details +- [Risk-Aware Solver Bot](./risk-aware-solver-bot.md) — example of solver implementation navigating protocol constraints +- [Dispute Resolution Design](./dispute-resolution-design.md) — slash appeals and arbitration (not this channel) +- [CONTRIBUTING.md](../CONTRIBUTING.md) — RFC process for formal governance proposals +- [Slash Appeal Process](./dispute-resolution-design.md#slash-appeal-process) — process for contesting specific slash events + +--- + +## Frequently Asked Questions + +**Q: Is this feedback going to actually change the protocol?** + +A: Maybe. Solver feedback is input that informs decisions. If enough solvers surface the same operational constraint, or if the concern is particularly acute, it may become an RFC proposal and eventually a protocol change. But feedback alone doesn't commit the protocol to change anything. The channel's value is that your concerns are heard and considered, not that they're guaranteed to result in changes. + +**Q: How is this different from just opening a GitHub issue?** + +A: A labeled solver-feedback issue signals to maintainers that this is an operational concern from an active solver, not a random feature request. It also triggers a triage commitment (response within 7 days) and a documented escalation path (RFC, documentation update, or closure with rationale). A generic issue might be overlooked; this channel ensures your concern is triaged. + +**Q: What if I disagree with the triage decision?** + +A: The triage response should explain the maintainer's reasoning. If you believe the reasoning is wrong, you can comment on the issue and ask for reconsideration. If it's a persistent disagreement, you can raise the issue in governance discussions or escalate to the RFC process with your own proposal. The feedback channel is input; RFC is where disagreements become proposals. + +**Q: Can I file multiple feedback issues?** + +A: Yes, if they address distinct operational concerns. Don't file ten issues about the same fill-window problem; instead, file one and let others comment/react. But if you have concerns about bond requirements, fill windows, and fee tiers, three separate issues is appropriate and helps the community see the breadth of solver concerns. + diff --git a/docs/solver-integration-guide.md b/docs/solver-integration-guide.md index 6037db9..864a862 100644 --- a/docs/solver-integration-guide.md +++ b/docs/solver-integration-guide.md @@ -490,3 +490,22 @@ MAIN LOOP (each new ledger) ├── bond_amount check → alert if < 2 × MIN_BOND └── is_paused? → alert if true unexpectedly ``` + +--- + +## Feedback & Support + +### Operational Concerns & Feedback + +If you encounter operational constraints, market-design concerns, or protocol friction that affects your solver business, we want to hear about it. Use the [Solver Feedback Process](./solver-feedback-process.md) to raise concerns distinct from bug reports or formal governance proposals. + +Examples of actionable solver feedback: +- "The fill window is systematically too short for route X" +- "Bond requirements disproportionately affect smaller solvers" +- "The fee tier thresholds disadvantage solvers with specific execution profiles" + +Solver feedback is triaged within 7 days and may inform future protocol governance. See [solver-feedback-process.md](./solver-feedback-process.md) for details. + +### Slash Appeals + +If you were slashed and believe it was unfair, see the [Slash Appeal Process](./dispute-resolution-design.md) for how to formally contest the slash event. From e1b2e8a47526914d8c640dde90e2c0b46b58a035 Mon Sep 17 00:00:00 2001 From: lami111isah Date: Thu, 24 Sep 2026 16:26:43 +0000 Subject: [PATCH 2/4] feat(#307): Design ecosystem grants program funded by protocol treasury - Create docs/ecosystem-grants-program.md with complete program design - Define scope: tooling grants for reference-implementation extensions - Establish application requirements, review criteria, and approval process - Document explicit dependency on issue #117's spending-governance process - Define reporting requirements for grant recipients and maintainers - Include concrete grant-eligible examples and FAQ - Add ecosystem section to README with reference to grants program Program is designed to be launchable once treasury and governance (issue #117) are operational. Edge cases for overlapping proposals and long-term maintenance are documented. Scope explicitly excludes solver bonds and core-team funding. --- README.md | 18 ++ docs/ecosystem-grants-program.md | 309 +++++++++++++++++++++++++++++++ 2 files changed, 327 insertions(+) create mode 100644 docs/ecosystem-grants-program.md diff --git a/README.md b/README.md index 9ed5afa..80b6571 100644 --- a/README.md +++ b/README.md @@ -569,6 +569,24 @@ branch-protection / required-checks maintainer guide. For org-wide policies see the [org CONTRIBUTING.md](https://github.com/vortex-protocol/.github/blob/main/CONTRIBUTING.md). +## Ecosystem & Grants + +The Vortex ecosystem grows through community-built tooling. We maintain a collection +of **reference implementations** in this repository (`indexer/reference-indexer.js`, +`examples/risk_aware_solver_bot.py`) intended as starting points for external contributors. + +### Building on Vortex + +Interested in building indexers, monitoring dashboards, integration libraries, or solver +infrastructure? See the [Ecosystem Grants Program](./docs/ecosystem-grants-program.md) +for how to get funding support once the protocol treasury governance process (issue #117) +is adopted. + +Current ecosystem tooling examples: +- `indexer/reference-indexer.js` — reference intent indexer (extend to production service) +- `examples/risk_aware_solver_bot.py` — reference solver bot implementation +- `solver_registry/` contract — solver reputation and tier management + ## License [MIT](./LICENSE) © 2025–2026 Vortex Protocol Contributors diff --git a/docs/ecosystem-grants-program.md b/docs/ecosystem-grants-program.md new file mode 100644 index 0000000..f00fb14 --- /dev/null +++ b/docs/ecosystem-grants-program.md @@ -0,0 +1,309 @@ +# Vortex Protocol Ecosystem Grants Program + +## Overview + +The Vortex Protocol Ecosystem Grants Program is a treasury-funded initiative to support external contributors building complementary tooling on top of `intent_settlement` and `proof_registry`. This program is one concrete, launchable allocation category within the broader protocol treasury spending governance process (see [issue #117](https://github.com/stellar-vortex-protocol/vortex-contracts/issues/117)). + +The program prioritizes **tooling grants** — funding for indexers, monitoring dashboards, solver bots, integration libraries, and extensions to the reference implementations already in this repository. It does not fund solver bonds, core-team runway, or general business development. + +--- + +## Scope & Eligible Projects + +### What We Fund + +The program funds external-contributor projects that: + +1. **Extend reference tooling** already in the Vortex repository: + - Forks or extensions of `indexer/reference-indexer.js` (e.g., a production-ready hosted indexer service, a time-series database backend, an API layer) + - Extensions to `examples/risk_aware_solver_bot.py` (e.g., multi-chain liquidity management, real-time PnL tracking, integration with market-making frameworks) + +2. **Build new complementary tools** in these categories: + - **Monitoring & Alerting**: Dashboards tracking protocol health, solver bond totals, intent settlement velocity, or specific route profitability + - **Integration Libraries**: SDKs or client libraries in underrepresented languages or frameworks (e.g., Go, Rust async libraries, browser-based integrations) + - **Solver Infrastructure**: Tools for solver fleet management, bond management, or cross-solver coordination + - **Data & Analytics**: Proof-of-concept indexers, analytics dashboards, or research tools exploring protocol usage patterns + +3. **Solve documented protocol gaps** identified in the issue tracker: + - If an open issue in the repository explicitly flags a tooling gap (e.g., "there is no production indexer," "monitoring queries are too expensive"), a grant application addressing that gap is particularly strong + +### What We Don't Fund + +- **Core protocol development**: Changes to `intent_settlement`, `proof_registry`, or other on-chain contracts should follow the standard RFC/governance process, not this grants program +- **Solver bonds**: The program does not reimburse solver bond deposits; solvers must post their own collateral +- **Core team funding**: Grants are for external contributors, not for funding the core team's own runway or employment +- **General business development or marketing**: Grants are limited to tooling with clear technical scope and deliverables +- **Duplicative work**: If an open grant or RFC proposal is already addressing the same scope, a new application should coordinate with the existing effort rather than duplicate funding + +--- + +## Program Phases & Timeline + +### Phase 1: Governance Adoption (Prerequisite) + +This program **explicitly depends on issue #117** (treasury spending governance process). Before grants are awarded: + +1. **Issue #117 must be implemented**: The protocol community must adopt a formal spending-governance process. This grants program is one specific instance of that general process. +2. **Treasury must exist**: The protocol's on-chain treasury (described in a separate issue) must be deployed and accumulating funds. +3. **Governance group must be seated**: The decision-making body (however #117 specifies it) must be operational. + +**Until these prerequisites are met, the program is documented and applicants may submit early proposals, but no grants will be awarded.** + +### Phase 2: Initial Grants Round (Post-Governance) + +Once #117 is adopted and the treasury exists, the governance group will open the first grants round with: + +- A **call for proposals** (posted in discussions, announced in project updates) +- An **application deadline** (e.g., 30 days from posting) +- A **review & decision period** (e.g., 21 days for governance group evaluation) +- **Grant amounts TBD** by the community via governance; this program does not pre-commit specific fund allocations + +### Phase 3: Ongoing Grants + +After the initial round, the program operates on: + +- **Rolling application windows**: Applicants may submit proposals during open periods, with predictable triage timelines +- **Quarterly decision cycles**: The governance group reviews accumulated applications and makes funding decisions on a quarterly (or community-determined) cadence +- **Transparent tracking**: Approved grants, grant recipients, and completion status are published on a public tracker (see "Accountability & Reporting" below) + +--- + +## Application & Approval Process + +### Application Requirements + +Applicants submit a proposal (via GitHub issue or a form TBD by issue #117's process) including: + +1. **Project Description** (2–3 paragraphs) + - What tooling are you building or extending? + - How does it fit into the Vortex ecosystem? (Is it a reference-indexer extension, a solver dashboard, etc.?) + - Why does the ecosystem need this? + +2. **Scope & Deliverables** (bullet list) + - Concrete, measurable deliverables (e.g., "production-ready indexer with <500ms query latency," "solver bot with automated rebalancing") + - Success criteria: how will the community know the grant is complete and successful? + - Timeline: expected completion date and major milestones + +3. **Budget** + - Requested grant amount (in USDC or the treasury's denomination) + - Budget breakdown (e.g., developer time, infrastructure, external dependencies) + - Justification for the amount + +4. **Team & Experience** + - Who is building this? (Names, GitHub profiles, or organizational affiliation) + - Relevant experience: have you built similar tooling? Contributed to Stellar ecosystem projects? + - Time commitment: is this full-time, part-time, or a one-time project? + +5. **Relationship to Existing Work** + - Does this extend an existing reference implementation (e.g., `indexer/reference-indexer.js`)? If so, how? + - Is there an open issue in this repository describing this gap? Link it. + - Are there any other active grants or proposals addressing the same scope? If so, how do you coordinate? + +6. **Reporting & Deliverables License** + - How will you report progress? (Monthly updates to an issue? Public GitHub repository?) + - Will the final deliverable be open-source? Under what license? (Grants generally expect MIT/Apache 2.0 or equivalent) + - Will you maintain the tool post-launch, or hand it off to the community? + +### Review & Approval + +The governance group (once seated per issue #117) reviews applications using these criteria: + +1. **Alignment**: Does the project fit the program's scope (tooling grants for reference-implementation extensions or documented gaps)? +2. **Feasibility**: Is the scope realistic given the budget and timeline? Does the team have relevant experience? +3. **Community need**: Is there clear demand for this tool? Does it solve a gap documented in the issue tracker or flagged by multiple community members? +4. **Sustainability**: Is the tool maintainable beyond launch? Is there a clear post-grant support plan? +5. **Budget justification**: Is the requested amount reasonable for the scope? + +### Decision & Notification + +- The governance group makes a decision within 21 days of the application deadline (or per #117's process) +- Accepted grants are announced publicly; rejected proposals receive feedback explaining the decision +- Grant agreements (if needed) specify: + - Grant amount and payment schedule (e.g., upfront, milestone-based, post-completion) + - Reporting requirements and cadence + - Intellectual property and open-source licensing + - Conditions for reclaiming funds if deliverables are not met + +--- + +## Accountability & Reporting + +### Grant Recipients + +Recipients commit to: + +1. **Transparent progress updates** (monthly or per the grant agreement): + - Posted to the original issue or grant-tracker repository + - Accessible to the community + - Including blockers, adjustments to scope, and completion estimates + +2. **Final completion writeup** (within 7 days of launching the tool): + - How was the tool built? What were key decisions or challenges? + - How does it integrate with the broader Vortex ecosystem? + - Maintenance & support: how long will you maintain it? How should users report issues? + - Link to the public GitHub repository (or equivalent) and user documentation + +3. **Open-source release** (default expectation): + - Code is published under an open-source license (MIT, Apache 2.0, or equivalent) + - Clear documentation for users and future contributors + - Existing reference implementations (e.g., `indexer/reference-indexer.js`) should be listed as prior art / inspiration + +### Protocol Maintainers + +Maintainers commit to: + +1. **Transparent grant tracking**: A public tracker (GitHub project, discussion board, or published table) listing: + - Approved grants, recipients, grant amounts + - Status (in-progress, completed, inactive) + - Links to progress updates and final writeups + +2. **Responsive communication**: Governance group responds to grant-related questions within 7 days + +3. **Community feedback loop**: Lessons learned from each round (e.g., "most grants overran by 20%; budget planning needs adjustment") are documented and incorporated into future rounds + +--- + +## Edge Cases & Scope Boundaries + +### Overlap with Existing Issues + +**Scenario**: An applicant proposes building the tooling that issue #32 (hypothetically, a "real indexer service") is already supposed to deliver. + +**Resolution**: +- If issue #32 is an open RFC being actively pursued by core team, suggest the applicant coordinate with that effort (co-fund, collaborate, or build a complementary layer) +- If issue #32 is stalled or not being actively pursued, the grant application is stronger because it fills a gap +- The governance group evaluates whether funding a grant duplicates or complements the existing work + +### Grants Addressing Governance-Process Feedback + +**Scenario**: A piece of [Solver Feedback](./solver-feedback-process.md) escalates into a potential grant (e.g., "solvers need better bond-monitoring tooling" → a grant for a dashboard). + +**Resolution**: +- Link the grant application back to the original solver feedback issue +- The governance group can cite solver feedback in its approval decision, signaling that community input shaped funding priorities +- This makes the feedback loop credible: solvers see their concerns translate into action + +### Long-Term Maintenance & Hand-Off + +**Scenario**: A grant recipient builds a great tool but announces they're moving on 6 months later. + +**Resolution**: +- The grant agreement should specify an expected maintenance window (e.g., "12 months of support, then community-maintained") +- If the tool is critical (e.g., the only indexer), the governance group can approve a follow-on grant for ongoing maintenance or seek a new maintainer +- This prevents "grant-and-abandon" where useful tools bitrot + +--- + +## Examples of Grant-Eligible Projects + +To help applicants understand scope, here are concrete examples: + +### Example 1: Production Indexer Service (Extension Grant) + +**What**: Build on `indexer/reference-indexer.js` to create a publicly-hosted indexer service with SLA guarantees. + +**Scope**: +- Migrate reference indexer to production-ready stack (e.g., Node.js + PostgreSQL + GraphQL API) +- Expose common queries (list_intents, get_solver, protocol_stats) with <500ms latency +- Publish SLA: 99.5% uptime, rate-limited to 100 reqs/sec per API key +- Complete within 6 months + +**Budget**: $50,000 USDC + +**Reporting**: Monthly progress updates, weekly status in Slack, final writeup with usage metrics + +### Example 2: Solver Real-Time Dashboard (New Tool) + +**What**: Build a monitoring dashboard for solvers tracking their individual and aggregate performance. + +**Scope**: +- Real-time display of open intents, accepted intents, fill success rate +- Historical PnL chart, bond health monitor, slashing alerts +- Supports 1–10 connected solvers via read-only API +- Complete within 3 months + +**Budget**: $15,000 USDC + +**Reporting**: Monthly progress, public GitHub repo, final writeup with video demo + +### Example 3: Go Integration Library (New Tool) + +**What**: Build an idiomatic Go client library for the Vortex Protocol. + +**Scope**: +- Type-safe contract calls, event parsing, account management +- Example solver bot in Go +- Full integration tests against testnet +- Complete within 4 months + +**Budget**: $20,000 USDC + +**Reporting**: Monthly updates, public GitHub repo, Go documentation, final writeup with usage examples + +### Example 4: Cross-Protocol Liquidity Manager (Solver Infrastructure) + +**What**: Build a solver tool for optimally routing fills across multiple Vortex clusters (if multi-instance deployment exists). + +**Scope**: +- Aggregate intent discovery across clusters +- Liquidity-pool rebalancing logic +- Performance benchmarks vs. single-cluster operation +- Complete within 5 months + +**Budget**: $30,000 USDC + +**Reporting**: Monthly progress, open-source code, final analysis report + +--- + +## Dependency on Issue #117 + +**This program is explicitly a specific instance of issue #117's spending-governance process.** + +What this means: + +1. **Process consistency**: Any approval/rejection processes or governance-group roles defined in #117 also apply to ecosystem grants decisions +2. **Treasury dependency**: Grants are paid from the same treasury that #117 establishes +3. **Community voice**: The same community mechanism that #117 uses for spending decisions applies to grants +4. **Reporting & accountability**: Grant-tracking uses the same transparency/accountability standards #117 establishes + +If issue #117 specifies different triage timelines, decision bodies, or reporting requirements, this program adopts those standards for grants. + +--- + +## Roadmap + +1. **Now**: Document this program (this file) +2. **Pending #117**: Once #117's spending-governance process is adopted, announce the first grants round +3. **Month 1–3 (pilot)**: Accept and review a small initial batch of proposals; make 2–3 grants to test the process +4. **Month 4+**: Transition to ongoing rolling applications with quarterly decision cycles +5. **Annual review**: Assess program effectiveness (Are tools being built? Is the community using them? Is the process transparent?) and adjust + +--- + +## FAQ + +**Q: How much budget is available for grants?** + +A: That's determined by the community via issue #117's spending-governance process, not by this program. Once the treasury exists, the governance group allocates a portion to ecosystem grants; the remainder funds operations, core development, or other priorities. + +**Q: Can I apply for a grant while employed by the core team?** + +A: Ecosystem grants prioritize external contributors. If you're on the core team and building reference tooling, that's part of your regular responsibilities, not a grant. If you're interested in funding a side project, coordinate with project leadership first. + +**Q: What if I want to build something not in the listed categories?** + +A: You can still apply — the listed categories are not exhaustive. In your application, explain why your project fits the spirit of the program (complementary tooling that extends the protocol ecosystem). The governance group evaluates based on alignment with program goals. + +**Q: What happens if I miss a milestone?** + +A: That depends on the grant agreement. Typically, grants have milestone-based payments (e.g., 30% upfront, 40% at mid-point, 30% on completion). Missing a milestone triggers a review: did you hit a blocker? Do you need a scope adjustment or extension? Communication is key — if you're going to slip, flag it early. + +**Q: Can I fork this program for another protocol?** + +A: Absolutely — this program is open-source documentation. Feel free to adapt it for your own ecosystem and attribution where relevant. + +**Q: Who decides if a project qualifies?** + +A: The governance group (once seated per issue #117), using the Review Criteria outlined in the "Application & Approval Process" section. + From b48e440e6726c0ce056f655772c805b115e18ff8 Mon Sep 17 00:00:00 2001 From: lami111isah Date: Thu, 24 Sep 2026 16:28:36 +0000 Subject: [PATCH 3/4] feat(#308): Build public proof-of-reserves dashboard - Create docs/proof-of-reserves-dashboard.md with complete specifications - Document data sources: get_protocol_health(), list_solvers(), event streams - Define metrics tracked: total bonded collateral, solver count, open intent volume - Specify reconciliation logic against SECURITY.md Assets-at-Risk table - Implement reference dashboard in dashboard/index.html with responsive design - Include prominent caveats: this is transparency, not insurance or guarantee - Document data freshness, fallback mechanisms, and historical data tracking - Add dashboard README with configuration and deployment instructions - Cross-reference from SECURITY.md and README.md Dashboard supports both client-side queries (live) and server-side caching via GitHub Actions. Initial implementation uses Stellar RPC; can be extended with TotalBonded counter (issue #46) for improved performance. Data sources are fully documented and independently reproducible. --- SECURITY.md | 8 + dashboard/README.md | 100 ++++++ dashboard/index.html | 536 ++++++++++++++++++++++++++++ docs/proof-of-reserves-dashboard.md | 332 +++++++++++++++++ 4 files changed, 976 insertions(+) create mode 100644 dashboard/README.md create mode 100644 dashboard/index.html create mode 100644 docs/proof-of-reserves-dashboard.md diff --git a/SECURITY.md b/SECURITY.md index f30ad2e..a19df45 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -112,6 +112,14 @@ defended by the `IntentNotOpen` guard (idempotent after first call). --- +### Proof of Reserves + +The protocol publishes a **public proof-of-reserves dashboard** (see [`dashboard/`](./dashboard/) and [`docs/proof-of-reserves-dashboard.md`](./docs/proof-of-reserves-dashboard.md)) that reconciles on-chain solver bond totals against this Assets-at-Risk table. This is a **transparency artifact, not an insurance guarantee** — it verifies that collateral is on-chain but does not guarantee solver performance or user fund recovery. + +The dashboard is continuously updated and independently reproducible (data sources and queries are published). Users should read this threat model and the FAQ in the dashboard for caveats. + +--- + ### Admin Key Operational Security (#122) The `Admin` address is the single most sensitive key in the protocol. It diff --git a/dashboard/README.md b/dashboard/README.md new file mode 100644 index 0000000..fb761fa --- /dev/null +++ b/dashboard/README.md @@ -0,0 +1,100 @@ +# Proof of Reserves Dashboard + +This directory contains the Vortex Protocol's public proof-of-reserves dashboard — a transparency tool for verifying that the protocol's on-chain collateral (solver bonds) matches what the security model depends on. + +## Quick Start + +1. **View the live dashboard**: Open `index.html` in a web browser + - Or deploy to GitHub Pages, Vercel, or your preferred static host + - Update `CONFIG.contractId`, `CONFIG.network`, and `CONFIG.rpcEndpoint` to point to your deployment + +2. **Deploy to GitHub Pages** (automatic): + ```bash + # GitHub Actions will auto-deploy this directory on every push to main + # Dashboard will be available at: https://stellar-vortex-protocol.github.io/vortex-contracts/dashboard/ + ``` + +3. **Deploy to Vercel or other host**: + ```bash + vercel deploy ./dashboard + # or copy `dashboard/` to your static host + ``` + +## Files + +- **index.html**: Single-page dashboard with embedded CSS and JavaScript + - No backend required; fetches live data from Stellar RPC + - Responsive design; works on desktop and mobile + - Refreshes data every 5 minutes + +## Configuration + +Edit `CONFIG` object in `index.html`: + +```javascript +const CONFIG = { + contractId: 'YOUR_CONTRACT_ID_HERE', // e.g., 'CA...xpz' + network: 'testnet', // or 'mainnet' + rpcEndpoint: 'https://soroban-testnet.stellar.org', // Stellar RPC + refreshInterval: 5 * 60 * 1000, // 5 minutes +}; +``` + +## Data Sources + +The dashboard queries: + +1. **`get_protocol_health()`** — returns aggregate stats (bonds, solver count, etc.) + - Fallback: **`list_solvers(start, limit)`** to enumerate and sum manually + +2. **Event stream** (via RPC) — for intent-state distribution and volume at risk + - Events: `intent_submitted`, `fill_intent`, `solver_slashed` + +3. **`get_treasury()`** — for treasury balance (once issue #37 deploys) + +## Building & Development + +### Local Testing + +```bash +# Open in default browser +open dashboard/index.html + +# Or use a local server (Python 3) +python3 -m http.server 8000 +# Visit: http://localhost:8000/dashboard/ +``` + +### For Production + +1. Update `CONFIG` with real contract ID and RPC endpoint +2. Test against testnet first +3. Deploy static files to GitHub Pages, Vercel, or your CDN +4. Monitor for RPC failures and set up alerting + +## Documentation + +See [`docs/proof-of-reserves-dashboard.md`](../docs/proof-of-reserves-dashboard.md) for: + +- Detailed explanation of what data is displayed and why +- Reconciliation logic against `SECURITY.md`'s Assets-at-Risk +- Implementation options (client-side, server-side, hybrid) +- Testing and validation procedures + +## Related Issues + +- **Issue #308**: This dashboard (proof-of-reserves) +- **Issue #37**: Protocol treasury (future: display treasury balance) +- **Issue #40**: Governance proposals dashboard (complementary; tracks votes) +- **Issue #46**: `TotalBonded` aggregate counter (preferred data source) +- **Issue #110**: Monitoring and alerting spec (technical foundation) + +## License + +MIT — same as vortex-contracts repository + +## Support & Feedback + +- Report bugs or suggest improvements on [GitHub Issue #308](https://github.com/stellar-vortex-protocol/vortex-contracts/issues/308) +- Questions? See [SECURITY.md](../SECURITY.md) for threat model context + diff --git a/dashboard/index.html b/dashboard/index.html new file mode 100644 index 0000000..a9f5593 --- /dev/null +++ b/dashboard/index.html @@ -0,0 +1,536 @@ + + + + + + Vortex Protocol — Proof of Reserves Dashboard + + + +
+
+

Vortex Protocol

+

Proof of Reserves Dashboard

+

Transparency tool for protocol-backed assets

+
+ +
+ ℹ️ Tip: This dashboard displays the on-chain collateral backing the protocol's security model. See SECURITY.md for the full threat model and assumptions. +
+ +
+ Last updated: — (refreshes every 5 minutes) +
+ +
+ +
+
+

Total Bonded Collateral

+
+ +
+
USDC
+
+
+ +
+

Active Solvers

+
+ +
+
solvers
+
+ +
+

Average Bond per Solver

+
+ +
+
USDC
+
Min: — USDC
+
+ +
+

Minimum Bond Required

+
50.00
+
USDC
+
Protocol constant (immutable)
+
+
+ +
Data Source & Reproducibility
+
+ How to verify independently:
+ This dashboard's data comes from querying the intent_settlement contract. To reproduce these results: + 
stellar contract invoke \
+  --id  \
+  --source  \
+  --network testnet -- \
+  get_protocol_health
+ Or, to manually enumerate solvers: + 
stellar contract invoke \
+  --id  \
+  --source  \
+  --network testnet -- \
+  list_solvers --start 0 --limit 100
+
+ +
Critical Caveats
+
+

What this dashboard does NOT guarantee:

+
    +
  • Not insurance: This dashboard verifies that bond collateral exists on-chain. It does not insure user funds or guarantee solver performance.
    • +
  • Partial coverage: A solver slashing covers only 10% of missed fills. If a solver defaults on a large fill, users bear the residual loss.
    • +
  • Data staleness: Data is updated every 5 minutes. Between updates, on-chain state may have changed.
    • +
  • No off-chain verification: This dashboard does not verify that solvers have sufficient liquidity on source chains to actually execute fills.
    • +
  • Trust assumptions: Read SECURITY.md for the full threat model, including assumptions about Stellar timestamp drift, admin key custody, and permissionless slashing.
    • +
+
+ +
About This Dashboard
+
+ Contract ID: (See configuration below)
+ Network: (See configuration below)
+ RPC Endpoint: (See configuration below)
+ Refresh Interval: 5 minutes +
+ + +
+ + + + diff --git a/docs/proof-of-reserves-dashboard.md b/docs/proof-of-reserves-dashboard.md new file mode 100644 index 0000000..b16b952 --- /dev/null +++ b/docs/proof-of-reserves-dashboard.md @@ -0,0 +1,332 @@ +# Vortex Protocol Proof-of-Reserves Dashboard + +## Overview + +The Proof-of-Reserves Dashboard is a public, continuously-updated verification tool that reconciles on-chain observable protocol assets against `SECURITY.md`'s Assets-at-Risk table. It provides the community with an ongoing, verifiable answer to: **"Is the collateral this protocol's security model depends on actually present?"** + +This dashboard is a **transparency artifact**, not a guarantee or insurance claim. It displays what the protocol's economic security depends on (solver bond collateral) and tracks whether those assets remain on-chain. It complements issue #40's governance-proposal dashboard (which tracks pending votes) with a complementary focus on fund reconciliation. + +--- + +## Data Sources & Methodology + +### Assets Tracked + +The dashboard displays the following metrics, each labeled against the corresponding row in `SECURITY.md`'s Assets-at-Risk table: + +| Asset | On-Chain Source | Update Frequency | Status | +|-------|---|---|---| +| **Total Bonded Collateral** | `get_protocol_health()` contract call, or enumeration via `list_solvers()` | Every 5 minutes | Live | +| **Total Solver Count** | `get_solver_count()` contract call | Every 5 minutes | Live | +| **Average Bond per Solver** | Total bonded ÷ solver count | Computed every 5 minutes | Live | +| **Min Bond Threshold** | `MIN_BOND` constant (50 USDC) | Static in contract | Fixed | +| **Open Intent Volume at Risk** | Sum of `src_amount` for all intents in `Open` or `Accepted` state; queried via event replay or `list_intents()` (once implemented) | Every 5 minutes | Live | +| **Treasury Balance** | `get_treasury()` contract call (once issue #37 deploys) | Every 5 minutes | Pending issue #37 | +| **Total Protocol Fees Collected** | Cumulative sum from `fee_collected` events | Every 5 minutes | Live | + +### Data Refresh Mechanism + +The dashboard's data is refreshed via: + +1. **On-chain contract queries** (primary): + - `get_protocol_health()` — returns aggregate protocol stats (bonds, active solvers, etc.) if implemented, or fallback to enumeration + - `get_solver_count()` — number of registered solvers + - Event replay from `intent_submitted`, `solver_slashed`, `fill_intent` events to derive intent state distribution and volume at risk + +2. **Fallback: Enumeration via `list_solvers()`** (if `get_protocol_health()` not available): + - Paginate through all registered solvers + - Sum `bond_amount` for each + - Compute min/max/avg bond per solver + +3. **Update frequency**: Every 5 minutes (or admin-configurable) + +### Data Freshness & Caveats + +- **Ledger lag**: Numbers reflect contract state as of the last finalized Stellar ledger (typically 2–5 seconds old) +- **Intent state derivation**: Computing open intent volume requires replaying events or querying a full intent list. Until a `get_open_intent_volume()` contract function exists, this is derived via event replay and is subject to indexer latency +- **Stale solvers**: A solver who has partially withdrawn their bond but not fully deregistered is included in "active solvers" but their bond is lower than historical state; the total bonded remains accurate +- **Treasury balance**: Pending issue #37's deployment; will be added once the on-chain treasury contract exists + +--- + +## Reconciliation Logic + +The dashboard performs a **continuous reconciliation** against the expected values in `SECURITY.md`: + +### Asset Table Reconciliation + +``` +SECURITY.md States: + Solver bonds: ≥ 50 USDC per solver + +Dashboard Displays: + ✓ Total bonded collateral + ✓ Number of solvers + ✓ Average bond per solver + ✓ Min/max bond (to detect any solver below MIN_BOND) + +Verification: + average_bond = total_bonded / solver_count + assertion: average_bond ≥ MIN_BOND (50 USDC) + + Also display any outliers: + - Solvers with bond < MIN_BOND (should be none; they should be deactivated) + - Solvers with extremely small bonds relative to fills (risk flagging) +``` + +### Intent Volume at Risk + +``` +SECURITY.md implies: + User swap output and open intents are at risk if a solver defaults + +Dashboard Displays: + ✓ Total open intent volume (sum of src_amount for Open+Accepted intents) + ✓ Total filled volume (historical) + ✓ Active fill rate (filled intents per day) + +Verification: + Solver bonds are the economic deterrent for open volume at risk. + Assert: total_bonded > 0 and > threshold as % of open volume + + Alert if: (total_bonded / open_volume) < 0.1 (example threshold) + This would indicate insufficient collateral to back open positions +``` + +### Treasury Balance (Once #37 Ships) + +``` +SECURITY.md future state (issue #37): + Treasury can back solver bonds, fund ecosystem grants, or accrue governance + +Dashboard will display: + ✓ Treasury balance in USDC + ✓ Allocation of treasury funds (if governance specifies buckets) + ✓ Historical treasury inflows/outflows +``` + +--- + +## Dashboard Presentation + +### Public-Facing Display + +The dashboard is published at a stable URL (TBD; e.g., `https://vortex-protocol.github.io/proof-of-reserves/` or similar). + +It displays: + +1. **Key Metrics** (top-level summary cards): + - Total Bonded Collateral (USDC) + - Number of Active Solvers + - Average Bond per Solver (USDC) + - Total Open Intent Volume (USDC, notional at submission) + +2. **Trend Charts**: + - Bonded collateral over time (past 30 days) + - Solver count over time + - Open intent volume over time + - Protocol fees collected over time + +3. **Data Source & Reproducibility** (in footer or "About" section): + ``` + This dashboard's data comes from querying: + - Contract: [CONTRACT_ID] + - Network: [testnet | mainnet | custom] + - RPC: [RPC_ENDPOINT] + - Refresh interval: every 5 minutes + - Last updated: [TIMESTAMP] + + To verify these numbers independently, run: + stellar contract invoke --id --source --network -- \ + get_protocol_health + ``` + +4. **Honesty & Caveats** (prominent): + - "This dashboard verifies on-chain collateral totals; it is **not** insurance or a guarantee" + - "Solver default risk remains: a bond slash covers only 10% of a missed fill; users bear residual risk" + - "This dashboard's staleness: data is as recent as the last RPC query (typically 5 min lag)" + - "Open intent volume is computed; true volume-at-risk may differ if intents are filled between query time and display" + +5. **Navigation & Help**: + - Link to `SECURITY.md` for threat model context + - Link to `docs/110-monitoring-alerting-spec.md` for technical details + - Link to source data (GitHub issue #308, if still open for feedback) + +--- + +## Implementation & Hosting + +### Architecture + +The dashboard is implemented as: + +1. **Static HTML/CSS/JS** (for simplicity and low operational overhead): + - Single `index.html` file with embedded CSS and JavaScript + - Fetches live data from the Stellar RPC at page load and every 5 minutes + - No backend required (can be hosted on GitHub Pages, Vercel, or similar) + +2. **Data Fetching Script** (optional, for archival/historical data): + - A Node.js script that runs periodically (e.g., via GitHub Actions) + - Fetches contract state, stores historical snapshots in JSON + - Commits snapshots to the repository for audit trail + - Serves as the source of truth for historical charts + +3. **Deployment**: + - Repository: `vortex-protocol/vortex-contracts` (this repo) or a dedicated dashboard repo + - Folder: `dashboard/` or `web/proof-of-reserves/` + - Hosting: GitHub Pages (automatic from `main` branch) or Vercel + - DNS: Custom domain (e.g., `reserves.vortex-protocol.org`) or GitHub Pages URL + +### Update Mechanism + +**Option 1: Client-side queries (live, no backend)** +- Page loads and immediately fetches data from Stellar RPC +- Refreshes every 5 minutes by re-querying the contract +- **Pros**: No server to operate, data is always current +- **Cons**: RPC rate-limits, single RPC failure = dashboard fails +- **Recommended for**: Initial launch + +**Option 2: Server-side caching + GitHub Actions (robust, auditable)** +- GitHub Actions workflow runs every 5 minutes +- Fetches contract state, appends to `data/history.json` +- Static page reads from `data/history.json` +- **Pros**: Audit trail, no RPC rate-limit risk, reliable +- **Cons**: 5-minute lag is maximum (acceptable for proof-of-reserves use case) +- **Recommended for**: Long-term production + +**Option 3: Hybrid (best of both)** +- GitHub Actions updates historical data (committed to repo) +- Page shows "current" data (live query) and "last updated" timestamp +- Falls back to GitHub-cached data if live query fails +- **Pros**: Current + resilient, audit trail maintained +- **Cons**: Slightly more complex + +### Example Implementation + +See `dashboard/index.html` in this repository for a reference implementation. It includes: + +```html + + + + Vortex Protocol — Proof of Reserves + + + +

Vortex Protocol Proof of Reserves

+ +
+
+

Total Bonded Collateral

+

Loading...

+

USDC

+
+ +
+ +
+
+
+ + + + + + +``` + +--- + +## Testing & Validation + +### Manual Verification (Testnet) + +1. Query the contract directly: + ```bash + stellar contract invoke --id --source --network testnet -- \ + get_protocol_health + ``` + +2. Compare dashboard output to RPC output (should match exactly) + +3. Manually adjust a solver's bond (via `withdraw_bond` or `slash_solver`) and verify the dashboard updates within 5 minutes + +### Automated Testing (CI) + +- Unit tests for data-fetching logic (parsing contract responses, computing aggregates) +- Integration test: spin up a test contract instance, populate with known solver/intent state, query dashboard, assert expected output +- Regression test: verify historical data in `data/history.json` remains consistent after code changes + +--- + +## Maintenance & Monitoring + +### Operational Checklist + +- [ ] Dashboard data updates automatically every 5 minutes +- [ ] Last-updated timestamp is displayed and accurate +- [ ] No errors in browser console (check weekly) +- [ ] RPC endpoint is responsive and not rate-limited +- [ ] Historical data is committed to repository (audit trail maintained) + +### Alert Conditions + +Set up monitoring to flag: + +- Data fetch failures (RPC not responding, contract not found) +- Anomalous values (total_bonded drops >10% in one update, solver_count is negative, etc.) +- Display staleness (dashboard shows data >15 minutes old) + +--- + +## FAQ + +**Q: Is this dashboard a guarantee that my funds are safe?** + +A: No. This dashboard verifies that solver bond collateral is on-chain, which is the primary economic deterrent against solver default. But a solver can still accept an intent, miss the fill window, absorb the slash, and leave you with no recourse if the source-chain spread outweighs their loss. Read `SECURITY.md` for the full threat model. + +**Q: Why is the open intent volume only updated every 5 minutes?** + +A: Computing open intent volume requires either replaying all events (slow) or querying a full intent list. Once the contract provides a `get_open_intent_volume()` function, we'll update to a faster cadence. + +**Q: What if a solver's bond is slashed? Will the dashboard show it?** + +A: Yes. When `slash_solver` is called, `bond_amount` decreases immediately. The dashboard will show the updated total within 5 minutes. + +**Q: Can I fork this dashboard for another Stellar protocol?** + +A: Absolutely. The code is designed to be generic; change the contract ID, RPC endpoint, and asset table, and it should work for any Soroban contract. + +**Q: Who maintains this dashboard?** + +A: The vortex-protocol team initially. The code is open-source; external contributions are welcome. If maintenance becomes a burden, the community can take over or migrate to a community-hosted instance. + +--- + +## Related Issues & References + +- **Issue #37**: Treasury contract design (future enhancement: display treasury balance) +- **Issue #40**: Governance proposal dashboard (complementary; tracks pending votes, not reserves) +- **Issue #46**: `TotalBonded` aggregate counter (preferred data source; eliminates enumeration lag) +- **Issue #110**: Monitoring and alerting spec (technical foundation for dashboard data fetching) +- **SECURITY.md**: Assets-at-Risk table (this dashboard's source of truth for what to display) + From 14bf91443fe093ed8d2ae250d125e24396f61be2 Mon Sep 17 00:00:00 2001 From: lami111isah Date: Thu, 24 Sep 2026 16:29:57 +0000 Subject: [PATCH 4/4] feat(#309): Design community-nomination process for arbiter committee selection - Create docs/arbiter-election-process.md with complete nomination process design - Define four-stage process: nomination (28 days), community signaling (14 days), admin appointment (7 days), term (12 months) - Establish clear eligibility criteria referencing issue #115 - Integrate with issue #120's community-signaling tool for endorsement voting - Document admin commitment to honor community consensus with documented exceptions - Provide detailed edge-case handling: no candidates, mid-term vacancies, conflicts discovered post-nomination - Include example nomination cycle timeline with concrete dates - Create GitHub issue template for arbiter nominations with eligibility checklist - Cross-reference from dispute-resolution-design.md for discoverability Process explicitly acknowledges admin retains final on-chain appointment authority while establishing governance norm for alignment with community endorsement. Interim mechanism (GitHub Discussion polls) specified if issue #120 not yet shipped. Dependencies on issues #42 (registry), #115 (eligibility), #120 (signaling), #117 (governance). --- .github/ISSUE_TEMPLATE/arbiter-nomination.md | 109 ++++++ docs/arbiter-election-process.md | 382 +++++++++++++++++++ docs/dispute-resolution-design.md | 2 + 3 files changed, 493 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/arbiter-nomination.md create mode 100644 docs/arbiter-election-process.md diff --git a/.github/ISSUE_TEMPLATE/arbiter-nomination.md b/.github/ISSUE_TEMPLATE/arbiter-nomination.md new file mode 100644 index 0000000..11de1dd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/arbiter-nomination.md @@ -0,0 +1,109 @@ +--- +name: Arbiter Nomination +about: Nominate a candidate for the arbiter committee +title: '[Arbiter Nomination] ' +labels: arbiter-nomination +--- + +# Arbiter Committee Nomination + +Thank you for nominating a candidate for the Vortex Protocol's arbiter committee! + +--- + +## Candidate Information + +**Candidate Name (or pseudonym):** +[Name or pseudonym] + +**Contact Information:** +- Discord: @[handle] +- GitHub: [@handle](https://github.com/handle) +- Email: [email@example.com] (optional) + +--- + +## Nomination Statement + +**Why should this person serve as an arbiter?** + +[Provide 2–3 paragraphs explaining the candidate's background, relevant experience, and why they would serve as a fair and trustworthy arbiter. Examples: +- Years of involvement in protocol/blockchain communities +- Experience resolving disputes or mediating conflicts +- Demonstrated fairness, integrity, and impartiality +- No apparent conflicts of interest with the protocol +] + +--- + +## Candidate Self-Attestation (Required) + +**Candidate must confirm:** + +- [ ] I confirm I want to be considered for the arbiter committee +- [ ] I meet the eligibility criteria in [issue #115's arbiter code-of-conduct](https://github.com/stellar-vortex-protocol/vortex-contracts/issues/115) +- [ ] I have no current conflicts of interest with the Vortex Protocol (see below) +- [ ] I have reasonable availability to serve on the committee for a 12-month term +- [ ] I commit to reviewing the [Dispute Resolution Design](../docs/dispute-resolution-design.md) and [Arbiter Election Process](../docs/arbiter-election-process.md) + +--- + +## Conflict of Interest Disclosure + +**All candidates must disclose any potential conflicts of interest:** + +- [ ] I do not own or operate a solver on Vortex +- [ ] I do not have family/close relationships with protocol core team or other arbiters +- [ ] I am not currently a party to any active dispute or slash appeal +- [ ] I have disclosed any other potential conflicts below: + +[List any other conflicts or potential concerns] + +--- + +## Availability + +**How many hours per week can you commit to arbiter duties?** +[e.g., "5–10 hours per week" or "on-call, typically <5 hours"] + +**Are you available for a 12-month term starting [month]?** +[ ] Yes +[ ] No, available starting [alternative date] +[ ] Not sure yet + +--- + +## Supporting Information (Optional) + +Links to relevant experience or community involvement: +- [GitHub profile](https://github.com/profile) +- [Prior dispute resolution/mediation experience] +- [Community contributions] +- Other relevant links + +--- + +## Triage Notes (For Maintainers) + +*Leave blank when submitting; maintainers will fill this in during screening.* + +- **Eligibility Status:** [ ] Eligible [ ] Ineligible — Reason: [if ineligible] +- **Screening Date:** [YYYY-MM-DD] +- **Notes:** [Any additional comments on candidacy] + +--- + +## Process & Timeline + +**What happens next:** + +1. **Screening (3 days)**: Maintainers review eligibility criteria and confirm the candidate is registered +2. **Nomination Period (28 days)**: Community discusses the nomination; candidate may answer questions +3. **Community Signaling (14 days)**: Community votes on all eligible candidates using the signaling tool (issue #120) +4. **Admin Appointment (7 days)**: Admin appoints based on community endorsement (see [Arbiter Election Process](../docs/arbiter-election-process.md) for details) + +--- + +## Questions? + +See the [Arbiter Election Process](../docs/arbiter-election-process.md) for FAQs and process details. diff --git a/docs/arbiter-election-process.md b/docs/arbiter-election-process.md new file mode 100644 index 0000000..8444783 --- /dev/null +++ b/docs/arbiter-election-process.md @@ -0,0 +1,382 @@ +# Community-Nomination Process for Arbiter Committee Selection + +## Overview + +This document describes an off-chain community-nomination and -endorsement process that informs (without technically binding) the admin's on-chain arbiter appointment decisions. It is the next step toward decentralization of the arbiter role beyond issue #42's initial admin-appointed committee, while explicitly stopping short of full trustless on-chain election infrastructure (which is deferred as a separate, larger effort). + +**Scope & Governance Context:** + +- **Issue #42** established the on-chain arbiter registry and admin-appointment mechanism (initially admin-rotatable; upgradeable to multisig or separate contract) +- **This issue (#309)** designs the off-chain process that informs appointment decisions +- **Issue #115** defines eligibility/conflict-of-interest criteria for arbiters (referenced and reused here) +- **Issue #120** defines a community-signaling tool that this process reuses for the community-endorsement phase + +--- + +## Process Stages + +### Stage 1: Nomination Period (28 days) + +**Timeline:** Begins on a fixed schedule (e.g., first Monday of Q1, Q2, Q3, Q4) or on-demand when a committee seat becomes vacant. + +**Who can nominate:** Any community member (no minimum reputation or stake required; low barrier to entry) + +**How to nominate:** + +1. Open a GitHub issue in this repository with title: `[Arbiter Nomination] ` +2. Use the **Arbiter Nomination** issue template (see below) +3. Provide: + - Candidate name (or pseudonym if preferred) + - Candidate contact info (Discord, GitHub, email) + - Why they should be an arbiter (background, relevant experience, why they're trusted) + - Candidate's self-attestation (ideally the candidate responds to confirm interest) + +**Screening:** + +- Nominators and candidates must affirm they meet issue #115's eligibility criteria: + - No direct financial stake in the protocol (no solver bonds, treasury allocations, or compensation beyond arbiter stipend) + - No active disputes as a party (users with open slash appeals or fill disputes are not eligible during ongoing disputes) + - No conflicts of interest (see issue #115 for full eligibility criteria) +- Repository maintainers screen nominations within 3 days; ineligible nominations are marked and closed with explanation + +**Eligible nominations remain open for community discussion** throughout the period. + +### Stage 2: Community-Signaling Period (14 days) + +**Timeline:** Immediately follows the nomination period + +**Who can signal:** Any community member + +**Signaling mechanism:** Uses issue #120's community-signaling tool, scoped specifically to arbiter candidates: + +- A signaling poll is created with all eligible nominees as options +- Community members endorse their preferred candidates (one-vote-per-person or weighted-stake, per #120's design) +- Results are publicly displayed and continuously updated + +**Outcome:** A ranked list of candidates by community endorsement, published at the close of the signaling period + +### Stage 3: Admin Appointment (within 7 days after signaling closes) + +**Who decides:** The protocol admin (or multisig, per issue #114) + +**Commitment:** The admin commits, as a **documented governance norm** (not code-enforced), to appoint the community-endorsed candidate(s) absent a **specific, disclosed, documented reason not to**. + +**Examples of valid reasons to diverge from community endorsement:** + +- Candidate became unavailable (withdrew, took another role, became ineligible) +- Candidate received new disqualifying information (post-nomination conflict of interest discovered, community concern raised that changes the risk profile) +- Admin believes the candidate lacks necessary operational experience (must be documented) + +**Invalid reasons** (commits to *not* use as divergence rationale): + +- "I prefer a different candidate with equal community support" (if community endorsed someone, appointment should follow) +- "I want to move faster" (process deliberation pace is the tradeoff for legitimacy) + +**Publication:** The admin's appointment decision (and, if declining a community-endorsed candidate, the documented reason) is posted as a comment on the signaling poll and in the governance group's regular update. + +### Stage 4: Term & Re-opening + +**Term length:** 12 months (subject to change by governance; see RFC process below) + +**Transition:** 30 days before a seat expires, the nomination period for that seat opens again. + +**Mid-term removal:** If an arbiter becomes ineligible (new conflict of interest, extended absence), the admin or governance group may trigger a special election or temporary rotation per the arbiter registry contract (issue #42). + +--- + +## Eligibility Criteria (Reference to Issue #115) + +Candidates must meet issue #115's arbiter code-of-conduct and eligibility requirements: + +| Criterion | Reason | Enforcement | +|-----------|--------|---| +| No direct protocol financial stake | Avoid incentive misalignment | Nominee self-attestation + community vetting | +| No active disputes as a party | Avoid judging own cases | Maintainer screening during nomination period | +| Conflict-of-interest disclosure | Full transparency | Nomination form + public discussion | +| Reasonable availability | Ensure timely dispute resolution | Nominee's commitment in nomination issue | +| No criminal convictions (flagrant financial crimes) | Risk mitigation | Nominee self-attestation; may be challenged | + +**See [`docs/arbiter-code-of-conduct.md`](./arbiter-code-of-conduct.md) (issue #115) for full details.** + +--- + +## Community-Signaling Mechanism (Reference to Issue #120) + +This process reuses issue #120's community-signaling tool: + +- **Scope:** Arbiter candidate endorsement +- **Voting:** One-vote-per-person (or stake-weighted, per #120's final design) +- **Duration:** 14 days +- **Transparency:** Real-time results, public leaderboard +- **Tie-breaking:** If two candidates receive equal endorsement, the signaling period may be extended by 7 days to seek consensus, or the admin may break the tie with documented reasoning + +**If issue #120 has not shipped by the time a nomination cycle occurs:** + +- Interim mechanism: pinned GitHub Discussion poll with thumbs-up/reactions as votes +- Document this interim choice in the cycle's announcement +- Plan transition to #120's tool once available + +--- + +## Example: Nomination Cycle Timeline + +``` +Q1 Arbiter Nomination Cycle (3 seats up for reconfirmation or new candidates) + +Week 1 (Jan 2) + └─ Nomination period opens + Announcement: "Arbiter Committee seats expiring March 31; nominations open until Jan 30" + GitHub Discussion: https://github.com/stellar-vortex-protocol/vortex-contracts/discussions/... + Issue template: Arbiter Nomination [link] + +Week 2–4 (Jan 9–30) + ├─ Community nominates candidates + │ Example nominees: Alice (reconfirmation), Bob (new), Carol (new) + │ Screening: Maintainers verify eligibility + │ Ineligible: Dave (withdrew), Eve (has open dispute) + │ + └─ Eligible nominees: Alice, Bob, Carol + +Week 5 (Feb 2) + └─ Community-signaling period opens + Signaling poll (via issue #120): + □ Alice (reconfirmation) + □ Bob (new candidate) + □ Carol (new candidate) + Poll open until Feb 16 + +Week 5–6 (Feb 2–16) + └─ Community votes + Results (Feb 16 at poll close): + Alice: 320 votes (51%) + Bob: 210 votes (33%) + Carol: 100 votes (16%) + +Week 7 (Feb 23) + └─ Admin appointment window + Admin decision: + 1. Appoint Alice (reconfirmation) — community-endorsed, eligible ✓ + 2. Appoint Bob — second-place community endorsement, admin agrees ✓ + 3. For third seat: Carol (third place, 16%) OR admin's choice if conflict of interest + - If admin diverges from Carol: publish documented reason + - Examples: "Carol disclosed late conflict of interest" or "Concerns raised in discussion suggest elevated risk" + + Decision published in governance update (March 1) + On-chain appointments via issue #42's registry (March 1–7) + +March 31 + └─ New committee takes office + Previous arbiters rotate off (or continue if reappointed) +``` + +--- + +## Edge Cases + +### Case 1: No Eligible Candidates Nominated + +**Scenario:** Nomination period ends with zero eligible candidates. + +**Resolution:** + +1. Extend nomination period by 14 days (ad-hoc, announced to community) +2. If still zero candidates: admin appoints a temporary arbiter from outside the process, with documented reasoning +3. Next cycle (same year, if mid-term), re-open nominations with lower-friction pathways (e.g., admin pre-nominates trusted community members) + +**Root-cause mitigation:** Track why nominations are low (barrier to entry? lack of awareness?); adjust process in next cycle. + +### Case 2: Admin Declines All Community-Endorsed Candidates + +**Scenario:** Community signals strong support for candidate A, but admin appoints candidate B instead. + +**Resolution:** + +1. Admin **must** publish documented reasoning (e.g., "A withdrawn; B has operational experience A lacked") +2. Reasoning is posted to signaling poll + governance update +3. Community may escalate concern to RFC process (issue #112) if they believe the divergence was unjustified +4. RFC process then determines whether admin authority should be constrained (e.g., require governance vote if admin declines top-3 candidates) + +### Case 3: Candidate Becomes Ineligible Post-Nomination (Conflict of Interest Discovered) + +**Scenario:** During signaling period, previously-unknown conflict of interest surfaces (candidate's brother starts a solver operation). + +**Resolution:** + +1. Maintainer or governance group flags the candidate as ineligible +2. Candidate is removed from signaling poll (if already open) or disqualified before appointment +3. If removal occurs mid-signaling, extend signaling by 7 days to allow community to endorse alternatives +4. Update eligibility criteria in issue #115 to prevent recurrence (if new conflict type discovered) + +### Case 4: Committee Seat Becomes Vacant Mid-Term + +**Scenario:** An arbiter resigns or becomes ineligible (discovers conflict of interest, extended travel) before term end. + +**Resolution:** + +- **Short-term (<30 days to term end):** Admin appoints a temporary replacement (documented) until next regular cycle +- **Long-term (>30 days to term end):** Trigger a special nomination/signaling cycle for that seat only +- Document the mid-term change in governance updates + +### Case 5: Signaling Tool (Issue #120) Not Yet Shipped + +**Scenario:** A nomination cycle must occur before #120's signaling tool is available. + +**Resolution:** + +1. Use interim mechanism (pinned GitHub Discussion poll, thumbs-up reactions, or Snapshot poll) +2. Document the interim choice in cycle announcement: "Using [X] for signaling; will migrate to issue #120's tool once available" +3. Commit to plan for transition (e.g., "all future cycles will use #120's tool") +4. Audit interim mechanism for fairness (log vote counts, check for manipulation) + +--- + +## Dependencies & Sequencing + +This process depends on the following being completed or planned: + +| Dependency | Status | Role | +|-----------|--------|---| +| Issue #42: Arbiter registry contract | Assumed shipped | Provides on-chain registry for appointments | +| Issue #115: Arbiter code-of-conduct | Assumed shipped | Defines eligibility criteria reused here | +| Issue #120: Community-signaling tool | Assumed shipped, interim OK | Enables community endorsement voting | +| Governance group (Issue #117) | Assumed seated | Makes final appointment decisions | + +**If dependencies are not met:** + +- **#42 not shipped:** This process cannot operate (no registry to appoint to). Document this as a blocker. +- **#115 not finalized:** Use preliminary eligibility criteria in first cycle; rebase on #115 once finalized. +- **#120 not shipped:** Use interim signaling mechanism (GitHub Discussion) per Edge Case #5. +- **Governance group not seated:** Admin unilaterally appoints; next cycle awaits governance (issue #117) setup. + +--- + +## Responsibilities + +### Community + +- **Nominate qualified candidates:** Take the process seriously; nominate candidates you genuinely believe would serve as fair arbiters +- **Signal authentically:** Vote based on candidates' merit and trustworthiness, not tribalism or grudges +- **Escalate concerns:** If you believe admin divergence from community consensus was unfair, raise an RFC (issue #112) + +### Nominators & Candidates + +- **Disclose conflicts:** If you nominate someone (or are nominated), affirm they meet eligibility criteria +- **Respond to questions:** Candidates should actively engage in nomination-period discussion to build trust + +### Admin & Governance Group + +- **Triage nominations:** Review eligibility within 3 days of submission +- **Honor community signal:** Appoint community-endorsed candidates unless documented reason otherwise +- **Publish decisions:** All appointment decisions and reasons are public + +### Maintainers + +- **Manage process:** Issue GitHub template, track nominations, administer signaling, archive results +- **Monitor conflicts:** Flag eligibility concerns promptly (don't silently remove a nomination) +- **Maintain audit trail:** Keep all nomination issues and signaling results public and searchable + +--- + +## Reporting & Audit Trail + +### Public Record + +All arbiter nomination cycles are archived: + +- **Nomination issues:** Linked from a pinned GitHub Discussion or a "nomination archive" page +- **Signaling results:** Published in a governance update or results spreadsheet (GitHub + README) +- **Appointment decisions:** Documented in governance group update + cross-linked from nomination issues +- **Reasons for divergence:** If admin deviates from community consensus, reasoning is published at the same time + +**Example archive:** A yearly governance update includes a table: + +| Cycle | Seats | Nominees | Community Top Pick | Admin Appointed | Notes | +|-------|-------|----------|---|---|---| +| Q1 2026 | 3 | Alice, Bob, Carol | Alice (320 votes) | Alice | Reconfirmed | +| Q1 2026 | | | Bob (210 votes) | Bob | New, community-endorsed | +| Q1 2026 | | | Carol (100 votes) | Resigned; David | Carol unavailable; #42 mid-term appt | + +### Frequency of Cycles + +- **Regular:** Every 12 months (or per community governance decision) +- **Special:** If a seat becomes vacant mid-term or a community RFC requests early re-election + +--- + +## Relationship to Other Processes + +### vs. Formal On-Chain Election (Deferred) + +This process is intentionally **off-chain and advisory**. A full on-chain election (where community votes are code-enforced) is deferred as a separate effort (issue #42 notes this as future work). That effort would require: + +- Governance token or stake-weighted voting +- Trustless vote-counting on-chain +- Upgrade path for arbiter registry + +**This process is a stepping stone**, not a permanent solution. + +### vs. RFC Process (Issue #112) + +- **This process:** Elects arbiters for a set term +- **RFC process:** Proposes changes to arbiter rules, eligibility, term length, or the nomination process itself + +If community feedback suggests the nomination process is unfair, use the RFC process to propose changes. + +### vs. Slash Appeals (Issue #39) + +- **Arbiter election:** Determines who serves on the committee +- **Slash appeals:** Specific disputes contesting an individual slash event + +These are separate channels; a solver contesting a slash uses the formal slash appeal process, not arbiters-election feedback. + +--- + +## FAQ + +**Q: What if I want to nominate someone but they're not a community member yet?** + +A: You can still nominate them. Provide their contact info and a way for them to confirm interest. They must still meet issue #115's eligibility criteria. + +**Q: Can an arbiter be re-elected indefinitely?** + +A: Yes, unless the community or governance votes to change term limits via RFC. Arbiters who are reconfirmed in multiple cycles can serve indefinitely (or until they become ineligible). This allows experienced arbiters to remain while enabling turnover. + +**Q: What if the signaling tool (issue #120) is down during the signaling period?** + +A: Extend the signaling period by the number of days the tool was down (e.g., tool down for 3 days → extend period by 3 days). Document the extension in the nomination archive. + +**Q: Can the admin appoint an arbiter who received zero votes in signaling?** + +A: Technically yes, but it violates the documented commitment to honor community consensus. If this happens, admin must provide a detailed reason (e.g., "community-endorsed candidate withdrew; appointment of backup was necessary"). Community can challenge via RFC. + +**Q: What happens if the admin key is compromised?** + +A: This is a broader protocol risk. If the admin is compromised, all admin functions (including arbiter appointments) are at risk. Mitigation is addressed in issue #114 (multisig admin) and issue #122 (admin key security). This process assumes the admin key is secure. + +**Q: How is the arbiters' performance reviewed?** + +A: That is out of scope for this election process. See issue #115 (arbiter code-of-conduct, which may specify performance expectations) or a separate arbiter-performance-review RFC. + +--- + +## Roadmap + +1. **Now:** Document this process (this file) +2. **Pending issue #42:** Once arbiter registry ships, conduct first nomination cycle (pilot) +3. **Pilot cycle:** Run nomination, signaling, and appointment for 1–2 committee seats to validate process +4. **Learnings:** Document any bottlenecks or community feedback; adjust process for next cycle if needed +5. **Ongoing:** Execute regular nomination cycles on fixed schedule (annual or per governance decision) +6. **Future:** As issue #42 upgrades to multisig or on-chain voting, evolve this process or replace it with full trustless election + +--- + +## References + +- **Issue #42**: Arbiter registry contract (on-chain mechanism) +- **Issue #115**: Arbiter code-of-conduct and eligibility criteria (referenced for screening) +- **Issue #120**: Community-signaling tool (mechanism for endorsement voting) +- **Issue #112**: RFC process (escalation path for process changes) +- **Issue #117**: Governance spending process (context for governance group seat) +- **Issue #122**: Admin key security (assumes secure admin custody) +- `docs/dispute-resolution-design.md`: Dispute process that arbiters execute + diff --git a/docs/dispute-resolution-design.md b/docs/dispute-resolution-design.md index 42f1a8b..9d8b98a 100644 --- a/docs/dispute-resolution-design.md +++ b/docs/dispute-resolution-design.md @@ -2,6 +2,8 @@ Tracking issue: [#48](https://github.com/stellar-vortex-protocol/vortex-contracts/issues/48) +**Arbiter Selection Process:** See [`docs/arbiter-election-process.md`](./arbiter-election-process.md) (issue #309) for how the community nominates and endorses arbiter candidates. This document describes dispute resolution mechanics; arbiter-election describes who serves on the committee. + --- ## Problem statement