> ## Documentation Index
> Fetch the complete documentation index at: https://docs.writz.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to Writz

Writz is open source. Contributions - bug reports, code improvements, documentation, and security research - are welcome. This page explains how to contribute effectively.

***

## Ways to Contribute

**Bug reports:** If you find a bug in any of the contracts, circuits, relayer, or bitcoin-script toolkit, open a GitHub issue with a minimal reproduction. Include the test case if possible.

**Code contributions:** See the open issues tagged `good first issue` or `help wanted` on GitHub. All contributions require tests. The CI must pass before merge.

**Documentation:** Spotted something unclear, incorrect, or missing? Open a PR directly against the `docs/` directory.

**Security research:** See the [Bug Bounty](https://docs.writz.xyz/security/bug-bounty.md) page for responsible disclosure guidelines and rewards.

**ZK ceremony participation:** The privacy edition (in progress, not part of v1) will need a Groth16 trusted setup ceremony with independent participants; it has no date yet. If you're interested in participating, [open an issue](https://github.com/WritzProtocol/writz/issues) (`writz.xyz` has no mailbox yet). No technical background required - participants just need to run a script and discard their randomness.

***

## Development Setup

```bash theme={null}
git clone https://github.com/WritzProtocol/writz.git
cd writz

# Install all dependencies. Note the package manager differs per module:
# Bun for bitcoin-script / relayer / frontend / packages/*, npm for circuits.
cd contracts && cargo fetch
cd ../privacy/contracts && cargo fetch
cd ../../bitcoin-script && bun install && bun run build
cd ../privacy/packages/commitment-tree && bun install
cd ../../../relayer && bun install
cd ../privacy/circuits && npm install
```

All 623 tests should pass on a clean checkout.

***

## Secrets

`relayer/.env.example` and `frontend/app/.env.example` are tracked deliberately, so
no `.gitignore` rule protects them, and a directory-wide `git add` stages
whatever they happen to contain.

A pre-commit hook scans staged additions for live-looking credentials, `sk_`
keys, Stellar `S...` seeds, Bitcoin WIF keys, PEM private key blocks and AWS
access key ids. Install it once per clone:

```bash theme={null}
git config core.hooksPath scripts/hooks
```

It reads staged content only, so it costs nothing on an unrelated commit and a
clean working tree cannot hide anything from it. Documentation placeholders like
`sk_...` or `sk_your_api_key_here` do not trip it.

Two habits the hook does not replace:

* Review the staged diff, not the list of filenames. A file showing as modified
  when you did not expect to touch it is the signal worth stopping on.
* Treat a pushed secret as published. Deleting the commit does not un-publish
  it, and an orphaned commit stays reachable by its SHA. Revoke first.

## Keeping the docs in sync

Contract addresses and test counts are quoted in a lot of places (README, SCF docs, community posts) and drift easily after a redeploy or when tests are added. Two scripts guard against that:

* After a redeploy, update `contracts/deployments/testnet.md` - it's the source of truth every other doc is checked against.
* After adding/removing tests, run `node scripts/update-test-counts.mjs` to regenerate `docs/_data/facts.json` from the real test suites.
* Before opening a PR that touches deployments or docs, run `node scripts/check-docs-sync.mjs` - it scans every `.md` file for contract addresses and "N tests" mentions that don't match the current truth, and CI runs it on every PR regardless.

***

## Code Standards

### Rust / Soroban Contracts

* Run `cargo fmt` and `cargo clippy` before committing
* Every public function must have a test
* Use `#[contractevent]` for all events - no deprecated `Events` API
* Per-entry persistent storage only - no growing `Vec` or `Map` in instance storage
* Manage TTL: every write to persistent storage must set TTL thresholds
* No `unwrap()` on user inputs - return errors via `Result` or panic with descriptive messages

### TypeScript (Relayer + Bitcoin Script)

* Run `bun run lint` before committing
* Every function must have a test covering the happy path and at least one error case
* No `any` types - explicit type annotations required
* Use the `Result<T, E>` pattern for operations that can fail

### Circom Circuits

* Every constraint must be intentional - document why it exists
* All public inputs must be explicitly marked `<== signal (public)`
* Test proof generation AND proof verification - not just compilation
* Test with both valid and invalid inputs - verify that invalid inputs are rejected

***

## Pull Request Process

1. Fork the repository and create a feature branch (`feature/your-feature`)
2. Make your changes with tests
3. Run `cargo test` (contracts), `bun test` (bitcoin-script), `bun run test` (relayer), `npm test` (circuits) - all must pass
4. Open a PR with a clear description of what changed and why
5. A maintainer will review within 5 business days

***

## Open Items

The following areas are actively looking for contributors:

| Area | Description | Skill needed |
| - | - | - |
| Frontend (app.writz.xyz) | React/Next.js frontend for Writz Lend | React, TypeScript, Stellar Wallets Kit |
| WASM prover integration | Integrate circom WASM prover in browser | TypeScript, snarkjs |
| Phase 2 ceremony tooling | Scripts for Powers of Tau Phase 2 ceremony | snarkjs, cryptography |
| Taproot migration | Upgrade P2WSH to P2TR for Phase 2 | Bitcoin Script, bitcoinjs-lib |
| SDK npm package | `writz-sdk` TypeScript package for SPV proof assembly | TypeScript, npm |
| Oracle integration | Integrate Pyth + Reflector SEP-40 adapters | Rust, Soroban |

If you want to work on any of these, open an issue first to discuss the approach before writing code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.