> For the complete documentation index, see [llms.txt](https://swappulse.gitbook.io/swappulse-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/contributing.md).

# Contributing to SwapPulse

Contribution standards, review expectations and release responsibilities.

Thanks for helping improve SwapPulse. The project aims to be open, community-driven and understandable to people who did not build the original system.

## Before you start

Read:

* [documentation home](https://swappulse.gitbook.io/swappulse-docs/)
* [V2 live architecture](https://swappulse.gitbook.io/swappulse-docs/network-and-web3/v2-live-architecture)
* [change protocol](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/change-protocol)
* [security audit](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/security-audit)

For chain work also read:

* [chain overview](https://swappulse.gitbook.io/swappulse-docs/network-and-web3/chain-overview)
* [operator guide](https://swappulse.gitbook.io/swappulse-docs/network-and-web3/operator-guide)

## Development principles

Contributions must preserve these defaults unless an explicitly reviewed protocol migration says otherwise:

* no private personal data on-chain;
* no privileged private keys or trusted signing logic in browser code;
* public RPC remains read-only;
* transaction relay remains authenticated and allowlisted;
* V2 verification failures/expiry/revocation fail closed for value-bearing actions;
* users retain self-custody and explicit signing for user-approved blockchain actions;
* Base44 entities use least-privilege row-level security;
* new UI copy is localised for all supported languages;
* accessibility is part of acceptance criteria, not an optional polish pass.

## Fork and branch workflow

1. Fork `beitmenotyou1/swappulse2` on GitHub.
2. Clone your fork.
3. Create a focused branch, for example:

```bash
git checkout -b feat/explorer-address-history
```

4. Make the smallest coherent change that solves the problem.
5. Run the relevant checks.
6. Commit with a clear message.
7. Push your branch to your fork.
8. Open a pull request against `main`.

## Frontend checks

Install dependencies:

```bash
npm install
```

Run the frontend locally:

```bash
npm run dev
```

Run the build/lint/test commands provided by `package.json` where relevant.

For UI changes, check:

* desktop and mobile layouts;
* keyboard-only use;
* focus visibility;
* screen-reader labels/landmarks;
* zoom and narrow viewports;
* reduced-motion/high-contrast/accessibility preferences;
* every supported interface language;
* no duplicate or unreachable navigation actions.

## Cairo/Starknet checks

Use the pinned chain toolchain and run:

```bash
cd chain
bash scripts/test-chain.sh
```

For relay policy changes also run:

```bash
cd chain/infra/tx-relay
node smoke-policy.mjs
```

Contract changes should include tests for the relevant negative path, not only the successful path. Depending on the feature, that may include unauthorised calls, duplicate/replay attempts, invalid state transitions, zero addresses, expiry, revocation, role changes, malicious callers and fuzz coverage.

## Security-sensitive changes

Call out security impact explicitly in the pull request when changing:

* authentication or permissions;
* Base44 RLS;
* blockchain transaction construction/signing;
* relay policy;
* verifier/admin authority;
* identity assurance;
* staking/slashing/rewards;
* bridge/replay handling;
* recovery;
* secrets/environment variables;
* public RPC behaviour.

Never include real secret values in an issue, commit, pull request, screenshot or test fixture.

## Data and privacy

Do not add names, email addresses, dates of birth, document images/numbers or other private identity evidence to Cairo storage or public events.

If a new feature needs sensitive information, keep it off-chain and document:

* why the data is needed;
* where it is stored;
* who can read it;
* how long it is retained;
* what public commitment/proof, if any, is written on-chain.

## Release expectations

Every pull request must make an explicit release-impact decision using [pull request checklist](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/contributing).

For significant updates, follow [release process](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/releasing) and update:

* [changelog](https://swappulse.gitbook.io/swappulse-docs/changelog);
* [versioned release notes](https://swappulse.gitbook.io/swappulse-docs/changelog);
* `RELEASE_MANIFEST.json`;
* `package.json` version where appropriate.

Do not backfill invented historical versions. Historical releases require a trustworthy preserved checkpoint/commit.

## Documentation expectations

Update docs in the same pull request when behaviour changes.

At minimum, consider whether the change affects:

* [documentation home](https://swappulse.gitbook.io/swappulse-docs/)
* [user guide](https://swappulse.gitbook.io/swappulse-docs/start-here/user-guide)
* [V2 live architecture](https://swappulse.gitbook.io/swappulse-docs/network-and-web3/v2-live-architecture)
* [change protocol](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/change-protocol)
* [deployment guide](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/deployment)
* [security audit](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/security-audit)
* [release process](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/releasing)
* [licensing guide](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/licensing) / [third-party notices](https://swappulse.gitbook.io/swappulse-docs/project-maintenance/third-party-notices) when third-party/licensing boundaries change
* [Frequently Asked Questions](https://swappulse.gitbook.io/swappulse-docs/faq), including whether the change raises a new user question that needs its own page

## Pull request checklist

Include:

* what changed;
* why it changed;
* screenshots for UI changes where useful;
* tests/checks run;
* security/privacy impact;
* migration/rollback notes if state or schemas changed;
* translation/accessibility notes for user-facing changes;
* FAQ review completed, with each new question added as its own page under `docs/faq/` and listed in `docs/SUMMARY.md`.

## AI-assisted contributions

AI tools are welcome. SwapPulse itself has been developed extensively with ChatGPT and Base44 under human direction.

AI-generated changes receive the same review standard as hand-written changes. Contributors remain responsible for understanding the code they submit, checking licences/attribution where applicable, running tests and avoiding invented APIs or insecure shortcuts.