Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Request the three developers for all changes; one approval is required.
* @ben-kaufman @cakesoft-utkarsh @Parsh
Comment thread
antuz123 marked this conversation as resolved.
Resolved
35 changes: 35 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
## Problem and change

<!-- Explain the problem, the resulting behavior and what is outside this PR. -->

Issue:
OpenSpec change / archived proposal:
Target branch:

## Test results

<!-- Include commands, platform/device and evidence. Mark unavailable checks as
not run or blocked. Manual verification is distinct from automated passes. -->

| Check / scenario | Platform | Passed / failed / blocked / not run | Evidence or reason |
| --- | --- | --- | --- |
| | | | |

## Review considerations

<!-- Describe any security/privacy, storage/migration, network, dependency or
hardware impact; use "none" where appropriate. State any known limitations.
Report suspected vulnerabilities privately per SECURITY.md, not in this PR. -->

- [ ] The diff excludes local secrets, wallet data and generated build/dependency files.
- [ ] Test failures and untested behavior are recorded above.
- [ ] The issue/spec and implementation describe the same scope.

Keeper maintainers own security review, acceptance, merging and official releases.
Passing checks does not constitute approval.

## Signoff

- Copilot review findings: <!-- Addressed, explained, or pending. Maintainer checks the actual comments. -->
- Developer approval: <!-- One approval required for sprint PRs. -->
- Product owner signoff: <!-- Link the owner's PR comment for product behavior, UX, or copy changes; otherwise state not applicable. -->
59 changes: 59 additions & 0 deletions .github/workflows/public-backend.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
name: Public backend setup

on:
push:
branches: [sprint, main]
paths:
- 'dev/local-backend/**'
- '.github/workflows/public-backend.yml'
pull_request:
branches: [sprint, main]
paths:
- 'dev/local-backend/**'
- '.github/workflows/public-backend.yml'
workflow_dispatch:

permissions:
contents: read

concurrency:
group: public-backend-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

jobs:
signing:
name: Public SigningServer adapter
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
persist-credentials: false
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: '22'
- run: ./dev/local-backend/dev prepare-signing
- run: npm ci --ignore-scripts
working-directory: dev/local-backend/.sources/signing
- run: npm run compile
working-directory: dev/local-backend/.sources/signing
- run: npm test
working-directory: dev/local-backend/.sources/signing

backend:
name: Local backend and bootstrap
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
persist-credentials: false
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
python-version: '3.9'
- run: python3 -B -m unittest discover -s dev/local-backend -p 'test_*.py'
- run: ./dev/local-backend/dev up
- run: ./dev/local-backend/verify-local.sh --persistence --boundaries
- name: Stop containers and retain volumes
if: always()
run: ./dev/local-backend/dev stop
128 changes: 128 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Contributing to Bitcoin Keeper

Contributions are welcome through forks and pull requests. Keeper
maintainers are responsible for code and security review, assessing privacy risks,
deciding whether to accept changes, and controlling merges and public releases.
Passing automated checks or submitting a working build does not constitute approval.

## Set up a local workspace

Fork this repository on GitHub and clone your fork for contributions. You do not
need write access to the Keeper repository or production credentials. Follow the
[local development guide](dev/local-backend/README.md) for tool versions, Docker
backend setup, Android Studio/Xcode builds and troubleshooting. Docker runs the
backend; native SDKs and the mobile app run on your host.

The [SigningServer source](https://github.com/KeeperCommunity/SigningServer) is
public and can be cloned, installed, built, tested and contributed to on its own.
The full Docker app/backend setup uses the public
[Relay](https://github.com/KeeperCommunity/Relay) and SigningServer sources;
it requires no repository invitation. Optional private development resources
follow a separate [access process](dev/local-backend/ACCESS.md). Access approval
is separate from acceptance of contributed code.

The guide's [capability table](dev/local-backend/README.md#what-works-locally) lists
supported local flows and unavailable integrations. The
[verification record](dev/local-backend/VERIFICATION.md) distinguishes tested
behavior from failures and untested platforms. Start with disposable testnet
wallets. Store accounts, release signing keys and production backend access are
not prerequisites for contributing.

## Develop a focused change

1. Find an existing issue or describe the problem in a new issue. For a suspected
vulnerability, use the private process in [SECURITY.md](SECURITY.md) instead.
2. Create a branch in your fork. Use the base branch associated with the issue;
if none is specified, use the repository's default development branch,
`sprint`. Do not assume a release tag includes every unreleased feature.
3. Capture the change's scope and acceptance criteria using the repository's
OpenSpec workflow. The CLI is included in the locked development dependencies:

```sh
yarn openspec new change your-change-name
yarn openspec status --change your-change-name
yarn openspec instructions proposal --change your-change-name
```

Follow the artifact instructions for proposal, specs, design and tasks. Read
[OpenSpec configuration](openspec/config.yaml); for UI changes, also read
[DESIGN.md](DESIGN.md). The repository's
[change-engineer workflow](.github/agents/change-engineer.agent.md) describes
planning, implementation and archiving. Respect any explicit repository-owner
restrictions on committing, pushing or publishing when using coding agents.
4. Implement the agreed scope, reuse existing components and keep unrelated
formatting, dependency upgrades, feature reconciliation and version bumps out
of the change. Maintainers coordinate version numbers and the
[Android](android/fastlane/README.md) and [iOS](ios/fastlane/README.md) release
workflows separately from local development.

`sprint` is the shared integration branch. Maintainers may use a temporary
release branch while a specific app version is stabilized. Carry fixes made on
that branch back into `sprint` so the shared development line stays current;
then follow the reviewed `dev` to `main` release promotion used by the project.

For backend development, bootstrap creates ignored checkouts under
`dev/local-backend/.sources/`. Save backend work in a branch/patch and submit it to
the appropriate backend repository; an app PR does not include those ignored
edits. Changes to packaged adapters must update the corresponding SHA-256 entries
in `sources.lock.json` and be verified from freshly prepared sources. Do not
package a generated checkout, database or signing volume in a PR.

## Test and report the result

Run checks relevant to the changed behavior. These commands run from the app root:

| Change | Checks |
| --- | --- |
| App logic | `yarn test --runInBand` (or the relevant Jest test paths) and `yarn lint` |
| User flow or native code | Build the affected development app and exercise the acceptance scenarios; use/update relevant Maestro flows under `flows/` |
| Local backend/bootstrap | `python3 -B -m unittest discover -s dev/local-backend -p 'test_*.py'` and `./dev/local-backend/dev verify` |
| Persistence or isolation | `./dev/local-backend/verify-local.sh --persistence --boundaries` on a disposable, otherwise idle Compose project |
| OpenSpec | `yarn openspec validate your-change-name --strict` |

Shared mobile changes should be checked on both Android and iOS. If a platform,
hardware device or integration is unavailable, say so; maintainers decide what
additional testing is required before acceptance. A local backend smoke test does
not validate recovery, transaction signing or every mobile feature.

Report the commands, commit, platform/device, actual results and relevant redacted
evidence. Keep **passed**, **failed/blocked** and **not run** separate. Describe
existing failures rather than hiding them or reporting an unexecuted check as a
pass. Screenshots can support manual verification but do not turn a failed
automated assertion into a passing automated test.

## Submit and review

Open a pull request from your fork and complete the supplied template. Link the
issue and OpenSpec artifacts, explain the behavior change and provide the test
results. Review the diff before submission: exclude local environment files,
generated dependencies, databases, keys, wallet backups and signing credentials.
Use [SECURITY.md](SECURITY.md) for private vulnerability details.

Keeper maintainers review correctness, product fit, security/privacy, dependencies
and test evidence. They may request revisions or additional tests, and decide
whether a change is accepted. Only authorized maintainers merge and release
official builds. Contributors do not need release permissions to participate.

Copilot code review is requested automatically for pull requests targeting
`sprint`. Read its actual comments and check each claim against the changed code
and relevant tests. Fix valid findings or explain why a comment does not apply
before requesting final human review. One developer approval remains the code
review gate. GitHub requests Ben, Utkarsh, and Parsh when a PR is ready for review;
any one can provide that approval. For changes to product behavior,
UX, or copy, the product owner
records separate product signoff in the PR discussion. A PR author's product
signoff does not count as GitHub's required developer approval.

Some existing CI checks use maintainer-managed services or secrets. If a check is
unavailable on a fork PR, report it in the PR so maintainers can arrange review;
do not request production secrets or treat an unavailable check as passing.
This document defines review responsibilities; it does not claim that GitHub
branch protection or approval rules have been configured or verified.

GitHub runs app tests and separate public backend/bootstrap checks. The existing Electrum/wallet integration
tests use public testnet nodes and fee services; an internet connection is needed.
Coverage, where generated, measures the configured Electrum/wallet source
directories, not every app screen. SonarCloud analysis on the development branch
is deferred; passing tests are not a security analysis pass. See [CI notes](dev/local-backend/CI.md)
for the branch-specific checks, deferred analysis work and evidence limits.
14 changes: 13 additions & 1 deletion Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,23 @@ Refer to platform-specific documentation for detailed setup requirements.
cd bitcoin-keeper
```
3. Install the project dependencies using Yarn:
The prepare scripts will automatically install pods and nodify crypto-related packages for react-native
The prepare script configures the crypto-related React Native packages.
CocoaPods is an explicit iOS setup step; follow [CONTRIBUTING.md](CONTRIBUTING.md)
after dependency installation.
```shell
yarn install
```

## Contributing and local backends

See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution process and
[the local development guide](dev/local-backend/README.md) for a reproducible
backend setup using public [Relay](https://github.com/KeeperCommunity/Relay)
and [SigningServer](https://github.com/KeeperCommunity/SigningServer) sources.
The local stack uses disposable testnet fixtures and needs no production
credentials. Keep native app builds on your host; the backend runs in Docker.
Report suspected vulnerabilities through [private reporting](SECURITY.md).

## Build and Run

### Varients
Expand Down
5 changes: 5 additions & 0 deletions dev/local-backend/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Copy to .env only when changing the defaults. No secrets required.
COMPOSE_PROJECT_NAME=keeper-contributor
KEEPER_RELAY_PORT=3000
KEEPER_CHANNEL_PORT=4002
KEEPER_SIGNING_PORT=3003
3 changes: 3 additions & 0 deletions dev/local-backend/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.sources/
.env
__pycache__/
24 changes: 24 additions & 0 deletions dev/local-backend/ACCESS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Optional private development resources

The public [app](https://github.com/KeeperCommunity/bitcoin-keeper),
[Relay](https://github.com/KeeperCommunity/Relay), and
[SigningServer](https://github.com/KeeperCommunity/SigningServer) can be cloned,
built, tested and contributed to without a Keeper invitation. The local Docker
setup in [README.md](README.md) uses only those public repositories and
disposable development identities. Production credentials are never needed.

Some assigned work may need separate private repositories, provider dashboards,
or test infrastructure. Ask the Keeper maintainer coordinating that work in your
existing private conversation. Include your GitHub username, task and the exact
resource needed. Do not post credentials or private access requests in a public
issue. If you do not have a maintainer contact, use the
[community contact](../../Readme.md#community) to reach one privately.

Maintainers review the work and grant only the needed permissions after checking
that the resource is ready to share. Approval covers the development access, not
every local command or proposed code change. Record invitation acceptance and
setup success in the internal development backlog. A contributor must use their
own GitHub identity; maintainers must not share personal tokens.

Security reports follow [SECURITY.md](../../SECURITY.md). Code acceptance,
merges, production access and releases remain separate maintainer decisions.
54 changes: 54 additions & 0 deletions dev/local-backend/CI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Contributor checks and analysis

## Public backend CI

The app's local backend workflow pins the public
[Relay](https://github.com/KeeperCommunity/Relay) and
[SigningServer](https://github.com/KeeperCommunity/SigningServer). It requires no
private repository token or production credential. The default branch runs
`Public backend setup` for the packaged adapter, bootstrap and disposable API
checks. Earlier Linux backend runs failed while fetching the private Relay;
those historical runs do not establish the result for this public pin.
Code acceptance and releases remain maintainer decisions.

## Active checks

The default branch's existing `Run Tests` workflow runs app tests. The new
`Public backend setup` workflow runs a separate public SigningServer adapter
fetch/install/compile/test job and full local backend bootstrap, API,
persistence and network-boundary checks. Neither job uses hosted credentials.
Pull requests are checked against their proposed merge with the target branch.
The development branch's `Contributor checks` workflow additionally publishes
app test coverage; its results are tracked with PR #7014.

Where generated, Jest's LCOV measures only the
Electrum/wallet directories listed in `jest.config.js`; this is not whole-app
coverage. Test success is evidence about the exercised cases, not a security
clearance. Maintainers retain security review and acceptance responsibility.

## SonarCloud deferred on 26 September 2026

The project owner chose to defer SonarCloud on the development branch. That job
was removed from its active workflow; app tests and an LCOV artifact remain there. `sonar-project.properties` is
retained for future restoration, including the report path and quality-gate wait
setting. No analysis or quality-gate pass is claimed, and no threshold has been
lowered. GitHub protection settings were not changed; if a required Sonar status
blocks merging, a maintainer must reconcile that setting with this decision.

Before deferral, PR #7014's original and updated scanners failed while retrieving
the pull request, before analysis. Public project metadata lists the repository
as `bithyve/bitcoin-keeper`, while this PR lives in
`KeeperCommunity/bitcoin-keeper`. This suggests a stale binding; an administrator
needs to verify the exact access/configuration problem when analysis is restored.

Deferred follow-up: inspect the project's Repository binding and GitHub app
access, confirm project/organization keys and the secret, restore a pinned scanner
that consumes LCOV and waits for its quality gate, then review the actual result.
Keep analyzer credentials away from fork code. See Sonar's
[repository binding instructions](https://docs.sonarsource.com/sonarqube-cloud/managing-your-projects/administering-your-projects/changing-binding).

The last existing `sprint` analysis (17 September, commit `1adf4f663`) reported a
failed quality gate: 0% new-code coverage, reliability rating C, 5.1% duplication
and 0% reviewed security hotspots, using a September 2024 previous-version
baseline. These are historical findings, not this PR's analysis. Deferral does
not resolve them or replace Keeper's review.
Loading
Loading