Thank you for your interest in improving Accord. This document is the authoritative contributor guide for this repository: how to set up your environment, how we expect changes to be proposed and reviewed, and how to work effectively with the project’s current prototype phase (dummy frontend data plus Soroban contract scaffold).
Please read the README first for product context, architecture, and security expectations.
- Code of conduct and collaboration
- Ways you can contribute
- Development setup
- Repository layout and boundaries
- Finding work and program participation
- Contribution workflow
- Branching, commits, and pull requests
- Coding standards
- Testing and quality gates
- Documentation
- Security and responsible disclosure
- Licensing
- Questions and maintainer contact
This project follows the Contributor Covenant Code of Conduct. By participating, you agree to uphold its standards.
- Be respectful and constructive. Review comments should focus on the change, not the person.
- Assume good intent and prefer clear questions over assumptions.
- Keep discussions on-topic in issues and pull requests (PRs).
Harassment, discrimination, or abusive behavior are not acceptable. Maintainers may remove disruptive content and, when necessary, block participation to protect contributors.
You do not have to write production Soroban code on day one. Useful contributions include:
| Area | Examples |
|---|---|
| Frontend | UI/UX improvements, accessibility, state handling, new pages or components wired to mock data |
| Contracts | Storage design, proposal lifecycle, tests, gas-friendly patterns, error handling |
| Quality | Tests, lint fixes, CI suggestions, reproducible bug reports |
| Documentation | README clarifications, diagrams, deployment notes, contributor onboarding |
| Reviews | Thoughtful PR reviews that catch edge cases, naming issues, or missing tests |
Small, focused PRs are easier to review and merge than large refactors bundled with unrelated changes.
| Tool | Purpose |
|---|---|
| Git | Version control |
| Node.js (LTS recommended) | Frontend (frontend/) |
Rust + wasm32v1-none (Soroban WASM target) |
Soroban contracts |
Stellar CLI (stellar) |
Build and test contracts from the repo root |
# Install Rust (if needed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# WASM target for Soroban (see Stellar CLI / Soroban docs if this changes)
rustup target add wasm32v1-noneInstall the Stellar CLI as described in the README (or the official Stellar docs).
From the repository root:
stellar contract build
stellar contract testcd frontend
npm install
npm run devOther useful commands:
npm run build # Typecheck + production build
npm run lint # ESLintOn Stellar, transactions (including contract deploy) pay a small fee in XLM. On testnet, that XLM is free play money with no real value. You do not need Freighter or another browser extension to deploy from the CLI: you only need a keypair (an “identity” in Stellar CLI) that holds a little testnet XLM.
1. Create a local deployer identity (this is your “wallet” for the CLI)
stellar keys generate accord-deployer
stellar keys public-key accord-deployerThe second command prints your public key (starts with G…). That account will pay fees when you pass --source-account accord-deployer to stellar contract deploy and similar commands.
2. Fund it with testnet XLM
Try the built-in faucet (uses the configured testnet RPC):
stellar network use testnet
stellar keys fund accord-deployer --network testnetIf that fails or rate-limits, use Friendbot in a browser: open
https://friendbot.stellar.org/?addr=YOUR_PUBLIC_KEY_HERE
(paste your G… address). You can also create/fund via Stellar Lab (account / friendbot tools).
3. Confirm you are on testnet for deploy commands
stellar network use testnet
# or pass --network testnet on each command4. Deploy (fees come from that same identity)
stellar contract deploy \
--network testnet \
--source-account accord-deployer \
--package accordHow this relates to “a wallet”
| Approach | What pays fees | Typical use |
|---|---|---|
| Stellar CLI identity | The key you generated (accord-deployer) |
Building, deploying, stellar contract invoke from terminal |
| Freighter / other wallet | Account you unlock in the browser | dApps, signing in the UI (your frontend does not use this yet) |
Keep your secret key / seed phrase private. For testnet-only keys, treat them as disposable if they leak, but still avoid committing them to git.
Explorers (for example Stellar Lab Contract Explorer) can show build verification only when a standard chain of evidence exists between the WASM on-chain and a public, automated build with GitHub Artifact Attestations. That process is described in SEP-0055: Contract Build Verification (discussion: stellar/stellar-protocol#1573).
In short, “verified” in the UI usually requires all of the following:
- Metadata inside the WASM (embedded at build time), including at least
source_repo=github:OWNER/REPO
and optionallyhome_domain=your.domain(forstellar.tomldiscovery per SEP-1). - A GitHub Actions workflow that builds the contract, runs
actions/attest-build-provenance, and publishes an attestation tied to the same WASM hash that was deployed. - Deploying the WASM produced by that pipeline (not a one-off local build), so the hash on the ledger matches the attested artifact.
If you deploy from your laptop with stellar contract deploy and no attestation pipeline, explorers will typically show unverified even though your code is public. That is expected: the UI is not saying your contract is malicious; it means no attested provenance record was found.
Practical options
| Goal | What to do |
|---|---|
| Green “verified” / Build info in Lab | Add a SEP-55-style release workflow (see SEP-0055 example YAML), use stellar contract build with --meta source_repo=github:${{ github.repository }} (and optional --meta home_domain=...), attest the WASM, then deploy the CI-built WASM (or wire deploy into CI). Reusable pattern: stellar-expert/soroban-build-workflow. |
| Trust without explorer badge | Keep the contract open source, tag releases, and document the WASM hash and commit; reviewers can rebuild and compare hashes manually. |
| Embed repo hint only | You can still pass --meta on stellar contract build / deploy so the WASM carries source_repo=...; explorers may show repo linkage, but full verification still depends on GitHub attestations as in SEP-55. |
Stellar’s docs note that even “Build verified” only proves an attested workflow built that WASM — you still must review the source and logic before trusting a contract.
Understanding where code belongs reduces review churn and merge conflicts.
src/types/accord.ts— Shared domain types (proposals, owners, stats). Extend these deliberately when the data model grows.src/data/mockData.ts— Temporary data layer until Soroban + wallet integration. New UI features should read/write through app state that is ultimately fed from here (or from a future API layer), not scattered magic constants.src/components/— Reusable presentational and small interactive pieces.src/pages/— Route-level or tab-level composition (dashboard, history, etc.).src/App.tsx— Shell: navigation, top-level state, and page switching. Avoid turning it into a dumping ground for feature logic.
Prototype rule: Unless an issue explicitly asks for Stellar network integration, avoid adding wallet/SDK dependencies that couple the UI to testnet/mainnet prematurely. Prefer mock-driven flows and clear seams (types + data module) so integration can land in one place later.
- The workspace is defined by the root
Cargo.toml(members = ["contracts/*"]). - Today the scaffold lives under
contracts/accord/. Future multisig work may addcontracts/multisig/(or similar); follow existing patterns inCargo.tomland sibling crates when adding packages.
frontend/node_modules/andfrontend/dist/— ignored viafrontend/.gitignore- Rust
target/— ignored from the repo root - Local Stellar/Soroban artifacts (see root
.gitignore)
Check ROADMAP.md for an overview of upcoming milestones, targeted features, and acceptance criteria. The roadmap helps you understand what is planned versus already shipped and where your contribution would have the most impact.
- Use open issues as the primary source of scoped work.
- Prefer issues that have a clear acceptance criteria (what “done” means, which files or behaviors are in scope).
Accord is positioned for participation in Stellar Drips Wave. Program rules can change by season; always follow the current official instructions for applying, claiming, or earning rewards.
General expectations:
- Do not start large work on an issue that is already assigned or actively being addressed by someone else, unless maintainers invite collaboration.
- Comment on the issue if you plan to pick it up, so effort is not duplicated.
- If the program requires application or assignment before coding, wait for that confirmation.
If an issue is labeled for Wave eligibility, treat the label as informational only until you confirm the latest program rules on the Drips site.
- Fork the repository (or gain push access to a contributor fork, if your team uses that model).
- Create a branch from
main(or the branch the maintainers designate as default). - Implement the smallest change that satisfies the issue, with tests where applicable.
- Run local checks (see Testing and quality gates).
- Open a pull request into the default branch with a clear title and description.
- Respond to review feedback in a timely way; it is normal to go through several review rounds.
- After your PR merges, clean up and move on (see below).
If you discover that an issue is wrongly scoped or blocked, comment on the issue early rather than investing days of work in the wrong direction.
Once your pull request is open, a maintainer will review it. Expect a first review within a few days; complex changes may take longer. Review comments appear directly on the PR in GitHub — on specific lines of code, on the overall diff, or as general discussion. Subscribe to email notifications for the PR so you do not miss feedback.
Reviewers check that the PR meets these conditions before approving:
- Tests pass. All CI checks (contract tests, frontend lint, and frontend build) are green.
- Scope matches the issue. The change addresses the issue it claims to fix without unrelated drive-by refactors.
- Coding standards followed. The code matches the style and patterns described in Coding standards.
- Description is complete. The PR description explains what changed, why, how to verify it, and links the relevant issue.
Once all criteria are met, a maintainer approves the PR and merges it into main.
When a reviewer requests changes:
- Push follow-up commits to the same branch. Do not open a new PR — the existing PR updates automatically.
- Reply to each review comment explaining what you changed or why you kept the current approach.
- Mark comments as resolved in the GitHub UI once the feedback has been addressed.
- If you disagree with feedback, push back with a counter-argument in the review thread. Explain your reasoning, link supporting references if applicable, and come to a consensus before proceeding. Reviewers are collaborators, not gatekeepers — discussion is expected.
- Delete your feature branch to keep the repository tidy. GitHub offers a button for this after merge.
- Your name appears in the commit history as a contributor to the project.
- Check the changelog (
CHANGELOG.md) to see your change listed in the next release, or follow the issue tracker for release announcements.
Use short, descriptive prefixes when possible:
| Prefix | Example |
|---|---|
feat/ |
feat/history-filters |
fix/ |
fix/proposal-card-a11y |
docs/ |
docs/contributing-setup |
chore/ |
chore/eslint-config |
contract/ |
contract/proposal-storage |
Maintainership may standardize naming further; follow any updated guidance in issues or pinned discussions.
- Use the imperative mood in the subject line (
Add,Fix, notAdded,Fixed). - Keep the first line around 72 characters or less when practical.
- Optionally add a blank line and a body explaining why the change was needed, especially for contracts and security-sensitive behavior.
A strong PR description helps reviewers and future readers. Include:
- What changed (high level).
- Why it was needed (link the issue:
Fixes #123orRefs #123). - How to verify (commands you ran, screenshots for UI).
- Risks or follow-ups (known limitations, TODOs that are intentionally left).
- One PR should address one concern (one issue, or one tightly related cluster of changes).
- Avoid drive-by refactors in files you are not required to touch.
- If you must refactor to implement a feature, say so in the PR and keep the refactor minimal and reviewable.
Use GitHub Draft PRs when you want early feedback on direction before the change is polished. Clearly mark what is incomplete.
- Strict typing: avoid
any. Prefer explicit types and narrow unions. - Components: prefer small, composable components; lift state only as high as needed.
- Accessibility: use semantic HTML where possible; label form controls; ensure keyboard operability for interactive elements.
- Styling: follow existing Tailwind usage; avoid one-off inline styles unless there is a strong reason.
- Imports: keep imports ordered in a readable way (no need for automated sorting unless the project adds a formatter rule).
-
Prefer clear names for storage keys, types, and public contract functions.
-
Document non-obvious invariants (for example, threshold bounds, owner uniqueness) in comments near the code that enforces them.
-
Keep error handling explicit; use typed errors where the Soroban project pattern supports it.
-
Avoid panics on user-controlled inputs; return errors that tests can assert.
-
Run
cargo clippy -- -D warningsbefore opening a PR and fix all lints it reports. You can enforce this automatically with a local pre-commit hook:# Create the hook file cat > .git/hooks/pre-commit << 'EOF' #!/usr/bin/env sh set -e cargo clippy -- -D warnings EOF # Make it executable chmod +x .git/hooks/pre-commit
The hook runs from the repository root on every
git commitattempt and aborts the commit if any clippy warning is found.
- Match the style and patterns of surrounding code unless an issue mandates a deliberate migration.
- Do not add secrets, private keys, or personal configuration to the repository.
Run the relevant checks before requesting review.
cd frontend
npm run lint
npm run buildstellar contract testSoroban tests may store snapshot files alongside the test source that capture expected contract output. When you make an intentional contract behaviour change a test may fail only because its stored snapshot no longer matches the new output — not because the logic is wrong.
To regenerate all snapshot files in one pass, set the UPDATE_EXPECT environment variable when running the test suite:
UPDATE_EXPECT=1 stellar contract testAfter regeneration, review each updated snapshot file to confirm the new output is correct, then commit the updated snapshot files alongside your code change. A PR that changes contract behaviour but omits the refreshed snapshots will fail CI.
If your change touches both areas, run both frontend and contract commands and state that in the PR.
- Contracts: add or extend tests alongside behavior changes. Prefer tests that encode invariants (for example, cannot execute below threshold).
- Frontend: when logic grows beyond trivial UI, consider unit tests or component tests if the project introduces a test runner; until then, document manual test steps clearly in the PR.
- Update the README when you change user-visible setup steps, prerequisites, or high-level architecture.
- Update this file when contribution rules or quality gates change.
- For small behavior changes, PR description may be enough; for new contributor-facing workflows, prefer durable docs in the repo.
Accord is not audited and is under active development. Treat it accordingly.
- Do not open public issues for unfixed security vulnerabilities.
- Use GitHub Security Advisories (or the contact process maintainers publish) for responsible disclosure.
If you are unsure whether something is a vulnerability, you may open a discussion or issue framed as a private security report per GitHub’s security policy, if enabled on the repository.
By contributing to this repository, you agree that your contributions will be licensed under the same terms as the project. See LICENSE (MIT).
If your employer owns your contributions, ensure you have authorization to contribute before opening a PR.
- General questions about how to contribute: open a GitHub Discussion if enabled, or an issue labeled for questions (if maintainers provide one).
- Issue-specific questions: comment on the issue thread.
- PR feedback: keep responses in the PR review thread so decisions stay searchable.
Thank you again for helping make Accord a solid, contributor-friendly Stellar project.