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

# Contributing

How to contribute to Enclave and SureSign: the rules that are not negotiable, what a good pull request contains, and how review works.

Contributions are welcome. The project holds a small number of rules absolutely, and asks for a particular discipline in pull requests because a wallet is not a place to move fast and fix later.

## The rules

These come from `AGENTS.md` and `.cursor/rules/` in the repository and apply to every contributor, human or agent.

1. **Minimize the trusted wallet, not the total wallet.** Interface, dApps, nodes, indexers, metadata, and remote APIs are untrusted. The Rust kernel is the only component that may construct, validate, or sign.
2. **No signing in JavaScript.** TypeScript contains zero lines of transaction construction and zero lines of private-key operations. No Kaspa serialization, Schnorr, sighash, or key derivation in the extension; no JavaScript cryptography for wallet secrets.
3. **No secrets in content scripts**, injected providers, logs, analytics, exception reports, or persisted plaintext.
4. **The ReviewPlan is semantic truth.** The interface renders the plan and cannot alter its meaning. Interface arithmetic derives from the plan, never from independent transaction math. Post-sign decode must equal the approved plan; a violation is a P0 release blocker.
5. **Unknown fails closed.** Unknown protocol semantics, covenant templates, and sighash types are refused, never approximated. Unverified upstream behaviour stays feature-gated.
6. **No remote executable packs.** Protocol packs ship in the repository. Remote sources carry data only.
7. **Consensus is not indexer truth.** Do not collapse them in APIs or copy.
8. **PSKT signs explicit inputs only**, honors the requested sighash exactly or rejects.
9. **Change is independently derived.** A dApp cannot declare an output to be change.
10. **Foundational types are owned centrally.** `Intent`, `Snapshot`, `ReviewPlan`, `Authorization`, `ProtocolPack`, `ChainSource`, `KeySource`: propose changes, do not fork the vocabulary.

If a change would relax any of these, it is not a pull request; it is a design discussion first.

## A good pull request

* **Small and focused.** One concern per PR.
* **Cites upstream.** Any consensus-sensitive change names the source commit or version it was read from (rusty-kaspa, a KIP, a KCC, a protocol's documentation) and updates `docs/UPSTREAM_MATRIX.md` if the pin moves.
* **Adds tests, positive and negative.** A new construction path comes with a vector that passes and an adversarial vector that is refused with the right invariant. A new screen comes with a gallery fixture. A new rule about copy or structure comes with a design-law test.
* **Updates docs.** The engineering record under `docs/` for design and pins; this site under `gitbook/` for anything a user or integrator can see.
* **Discloses assumptions and unknowns.** Say what you verified and what you did not. Report an unknown rather than invent a behaviour.
* **Rebuilds the kernel** (`scripts/build-kernel-wasm.sh`) and commits `extension/public/wasm` when anything under `core/` changed.
* **Passes CI**: Rust tests with and without `wasm`, extension typecheck and tests, `npm audit`, `cargo deny`.

## Review

Every pull request is reviewed. Security-critical pull requests (anything under `core/`, `extension/src/protocol/`, `extension/entrypoints/`, the manifest, the build and release scripts, the dependency lockfiles) are never auto-merged and require a maintainer's explicit approval. Consensus-sensitive changes are checked against the cited upstream before merge.

## Definition of done for a transaction feature

A feature that creates transactions is not done when a transaction succeeds on a network. It is done when: the authoritative upstream behaviour is documented; a typed intent exists; construction, independent validation, and semantic effects exist; the ReviewPlan renders it; positive vectors pass; adversarial vectors are refused; relevant fuzz or property tests exist; post-sign equivalence passes; interrupted-state recovery is handled where applicable; developer documentation is updated; a security reviewer has signed off; and the feature's maturity is represented correctly in the interface.

## Style

Rust: `#![forbid(unsafe_code)]`, no panics on hostile input, secrets in zeroizing types, errors that name the invariant. TypeScript: strict mode, no `any` at the protocol boundary, no inline styles (the extension's content security policy forbids them), copy that a user would understand with no developer-facing notes on screen. Both: prefer fewer features with proven semantics over more with ambiguous ones.

## Communication

Bug reports and requests go to the feedback board at [enclave.fider.io](https://enclave.fider.io/). For a security-sensitive finding, do not post publicly; see [Security](/argon-docs/developers/security.md).