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

# Developer guide

## Development rules

* Keep every runtime path read-only. Do not add transaction submission, signing, or private-key handling.
* Keep Stellar SDK response types inside the RPC adapter. Other packages use ControlWatch domain types.
* Put contract-specific function names, event topics, and error codes in `pkg/surface` only after verification against pinned source or testnet.
* Represent failed measurements as `UNMEASURABLE`; never convert an RPC or decoding failure into a finding.
* Sort sets and map-derived output before serialization or rendering.
* Add table-driven tests for behavior changes.

## Before committing

Run:

```bash
gofmt -w <changed-go-files>
go test ./...
go vet ./...
staticcheck ./...
```

Use conventional commit messages and keep commits focused on one logical unit. Stage files by explicit path and do not commit secrets, `.env` files, generated binaries, or live snapshot data.

## Integration tests

Tests that contact Stellar testnet must use the `integration` build tag and the contract IDs generated by the sibling fixture repository. Default tests must remain deterministic and offline.