ci: unittest from source, hash-pinned CI tools, CONTRIBUTING.md

.github/requirements/build.in

@@ -0,0 +1 @@
+build==1.6.1

.github/requirements/build.txt

@@ -0,0 +1,14 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile --generate-hashes --python-version 3.13 .github/requirements/build.in -o .github/requirements/build.txt
+build==1.6.1 \
+    --hash=sha256:51cc11666391ab6f092070437ac747002ff46f3e4113a3622177ee6b488bfc53 \
+    --hash=sha256:ecd351a4be9d35a9eaaba244a7687143c9c7d4aea6ac964e7e7ddab20cbcf4e7
+    # via -r .github/requirements/build.in
+packaging==26.3 \
+    --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 \
+    --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+    # via build
+pyproject-hooks==1.3.3 \
+    --hash=sha256:5fc53fdac9f7bd63fbcdc868fb5f90b4784d78a53a3d3388cd738b807441a20b \
+    --hash=sha256:defda19b854fa0d3bd4f76ea4ddcba8abd7dcfcdd585a6690ade050744fc5f43
+    # via build

.github/requirements/lint.in

@@ -0,0 +1,2 @@
+ruff==0.16.9
+mypy==2.3.1

.github/workflows/live-smoke.yml

@@ -21,5 +21,4 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
-      - run: pip install -e .
       - run: python .github/scripts/live_smoke.py

.github/workflows/release.yml

@@ -26,7 +26,8 @@ jobs:
         run: |
           v=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
           test "v$v" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME does not match version v$v"; exit 1; }
-      - run: pip install build && python -m build
+      - run: pip install --require-hashes -r .github/requirements/build.txt
+      - run: python -m build
       - name: Smoke-test the built wheel
         run: |
           python -m venv /tmp/wheel-env

.github/workflows/tests.yml

@@ -24,8 +24,8 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
-      - run: pip install -e . pytest
-      - run: python -m pytest tests/ -v
+      - name: Run the suite from source — zero dependencies, nothing to install
+        run: python -m unittest discover -s tests -t . -v
 
   os-compat:
     runs-on: ${{ matrix.os }}
@@ -41,8 +41,8 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
-      - run: pip install -e . pytest
-      - run: python -m pytest tests/ -v
+      - name: Run the suite from source — zero dependencies, nothing to install
+        run: python -m unittest discover -s tests -t . -v
 
   package:
     runs-on: ubuntu-latest
@@ -53,7 +53,8 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
-      - run: pip install build && python -m build
+      - run: pip install --require-hashes -r .github/requirements/build.txt
+      - run: python -m build
       - name: Test the wheel as users get it (not the source tree)
         run: |
           python -m venv /tmp/wheel-env
@@ -75,7 +76,7 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
-      - run: pip install ruff==0.16.9 mypy==2.3.1
+      - run: pip install --require-hashes -r .github/requirements/lint.txt
       - run: ruff check btc_toolkit/ tests/
       - name: Type check (the package ships py.typed, so its types are a promise)
         run: mypy --strict btc_toolkit/

CHANGELOG.md

@@ -9,6 +9,14 @@ versioning follows [SemVer](https://semver.org/). The `--json` output follows th
 ### Added
 - CodeQL static analysis (SAST) of the Python package and of the GitHub Actions workflows, on every push and pull request.
 
+### Changed
+- CI runs the test suite with the standard library's `unittest`, straight from the source tree: no package
+  and no test runner are installed. `pytest` still works for contributors who prefer it.
+- The CI tools that are still installed (`build`, `ruff`, `mypy`) are pinned by hash in `.github/requirements/`
+  and installed with `--require-hashes`: a tampered package on PyPI fails the build instead of running in it.
+- `CONTRIBUTING.md` documents the contribution process and requirements, including tests with every change.
+- `SECURITY.md` links the private vulnerability reporting form directly and commits to a 14-day initial response.
+
 ## [1.6.0] — 2026-09-27 — Typed
 
 ### Added

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to btc-toolkit
+
+Thanks for considering a contribution. Bug reports, questions and pull requests
+are all welcome.
+
+## Reporting bugs and requesting features
+
+Open an [issue](https://github.com/devdavidejesus/btc-toolkit/issues). For a bug,
+include the command you ran, what you expected, what happened, and the output of
+`btc-toolkit --version`. Transaction IDs and addresses are public data, so
+including them is fine.
+
+**Security issues are different:** please do not open a public issue. Follow
+[`SECURITY.md`](https://github.com/devdavidejesus/btc-toolkit/blob/main/SECURITY.md).
+
+## How changes are made
+
+1. Fork the repository and create a branch from `main`.
+2. Make your change, with tests (see below).
+3. Open a pull request against `main`. Every pull request runs the full CI:
+   the test suite on Python 3.10–3.14 (Linux) and on macOS and Windows, a test of
+   the built wheel, `ruff`, `mypy --strict` and CodeQL. `main` is protected — a
+   pull request can only be merged when all required checks pass.
+4. The maintainer reviews and merges. Releases are cut from `main` by tag and
+   published by GitHub Actions (see
+   [`docs/releases.md`](https://github.com/devdavidejesus/btc-toolkit/blob/main/docs/releases.md)).
+
+## Requirements for contributions
+
+- **Standard library only.** btc-toolkit has zero runtime dependencies; a change
+  that adds one will not be merged.
+- **Tests come with the change.** New functionality and bug fixes must include
+  tests in `tests/`, written with `unittest`. All API calls are mocked — the
+  suite must run offline.
+- **Types and lint are clean:** `mypy --strict btc_toolkit/` and
+  `ruff check btc_toolkit/ tests/` pass.
+- **The `--json` output is a contract.** Follow the stability policy in
+  [`docs/json-schema.md`](https://github.com/devdavidejesus/btc-toolkit/blob/main/docs/json-schema.md):
+  adding keys is fine; renaming or removing them needs a major version.
+- **Claims are verifiable.** Any transaction ID, address or on-chain fact in docs
+  or tests must be checkable against the chain.
+- User-visible changes get a line in
+  [`CHANGELOG.md`](https://github.com/devdavidejesus/btc-toolkit/blob/main/CHANGELOG.md) under `[Unreleased]`.
+
+## Running the checks locally
+
+```bash
+python -m unittest discover -s tests -t . -v   # tests — nothing to install
+pip install ruff mypy                            # only for lint and types
+ruff check btc_toolkit/ tests/
+mypy --strict btc_toolkit/
+```
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](https://github.com/devdavidejesus/btc-toolkit/blob/main/LICENSE).

README.md

@@ -240,10 +240,10 @@ Zero external dependencies — Python standard library only (`urllib`, `json`, `
 ## Testing
 
 ```bash
-python -m pytest tests/ -v
+python -m unittest discover -s tests -t . -v
 ```
 
-149 tests, all API calls mocked — the suite runs offline. The package is type-checked with `mypy --strict` and ships `py.typed`. A separate weekly job reads known on-chain facts from mainnet.
+149 tests, all API calls mocked — the suite runs offline, from the source tree, with nothing to install (`pytest` works too if you prefer it). The package is type-checked with `mypy --strict` and ships `py.typed`. A separate weekly job reads known on-chain facts from mainnet.
 
 
 ## How balance is computed
@@ -359,7 +359,7 @@ btc-toolkit is free, MIT-licensed and has no sponsor. If it's useful to you, you
 
 ## Contributing
 
-Found a bug or want to propose or build a new command? Open an [issue](https://github.com/devdavidejesus/btc-toolkit/issues) or a PR. Every contribution must keep the core rules: stdlib only, tests mocked, claims verifiable on-chain.
+Found a bug or want to propose or build a new command? Open an [issue](https://github.com/devdavidejesus/btc-toolkit/issues) or a PR. Every contribution keeps the core rules — stdlib only, tests with every change, claims verifiable on-chain. The process and requirements are in [`CONTRIBUTING.md`](https://github.com/devdavidejesus/btc-toolkit/blob/main/CONTRIBUTING.md).
 
 ---
 

SECURITY.md

@@ -69,7 +69,11 @@ a package before installing it.
 ## Reporting a vulnerability
 
 Please **do not** open a public issue for security-sensitive reports.
-Email the maintainer at the address on the GitHub profile
-([@devdavidejesus](https://github.com/devdavidejesus)) or use GitHub's
-private vulnerability reporting on this repository if enabled. You will get a
-response within a few days; fixes ship as patch releases with a changelog note.
+Report privately through GitHub:
+[**Report a vulnerability**](https://github.com/devdavidejesus/btc-toolkit/security/advisories/new)
+(the report is visible only to you and the maintainer). If you can't use GitHub,
+email the maintainer at the address on the GitHub profile
+([@devdavidejesus](https://github.com/devdavidejesus)).
+
+You will get an initial response within 14 days — usually much sooner. Fixes
+ship as patch releases, and the release notes identify the fixed issue.