Contributor Quickstart

A focused checklist for engineers contributing features or fixes to the Keythings Wallet monorepo.

1. Read the essentials

  • README.md — project overview, scripts, and CI expectations.
  • CONTRIBUTING.md — contribution guidelines and review expectations.
  • SECURITY.md — security policy, reporting process, and runbook.
  • ADR index: Architecture Decisions.

2. Set up your environment

  1. Clone the monorepo and run bun install at the root.
  2. Start the dev server with bun run dev and load the unpacked extension from dist/ when needed.
  3. Verify you can run bun run lint without errors before making changes.

3. Implementing a change

  1. Create a feature branch from main.
  2. Make focused commits; keep UI, background logic, and wallet-core changes logically separated.
  3. Prefer Zod for all new validation logic (inputs, RPC payloads, configuration, and external data). Avoid usingtry/catch as a validation mechanism.

4. Required checks before opening a PR

At minimum, run the following from the monorepo root:

  • bun run lint
  • bun run build (run once per change set; re-run only if you fixed a build issue)
  • bun audit

For extensions to wallet-core or security-sensitive paths, also run:

  • bun run test:unit
  • bun run test:integration
  • bun run test:e2e (when you change flows that impact popup UX or approvals)
  • bun run security when modifying crypto, session, or capability logic.

5. Documenting decisions

  • When you change storage, network mapping, or permission behaviour, add or update an ADR underdocs/adr/ and reference it in your PR description.
  • For smaller changes, update the relevant docs page in keythings-docs (for example, API reference or architecture map) to keep external docs aligned with behaviour.

6. Opening a pull request

  • Include a short summary of the change and the problem it solves.
  • List the commands you ran (lint, build, tests, security) and their results.
  • Link to any new or updated ADRs and docs pages.
30 of 33