{"id":26748096,"url":"https://github.com/aido/walletwatcher","last_synced_at":"2026-04-18T17:03:50.880Z","repository":{"id":283869794,"uuid":"944803849","full_name":"aido/WalletWatcher","owner":"aido","description":"Provides a secure method for monitoring the balance of a cold wallet without compromising its security.","archived":false,"fork":false,"pushed_at":"2025-03-22T17:21:37.000Z","size":123,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-03-22T18:27:58.327Z","etag":null,"topics":["android","bitcoin","cryptocurrency","python","security","wallet"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aido.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-08T02:02:45.000Z","updated_at":"2025-03-22T17:21:41.000Z","dependencies_parsed_at":"2025-03-22T18:29:29.729Z","dependency_job_id":"fe5261de-5e54-42e4-b5e9-70b76bd4175d","html_url":"https://github.com/aido/WalletWatcher","commit_stats":null,"previous_names":["aido/walletwatcher"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aido%2FWalletWatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aido%2FWalletWatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aido%2FWalletWatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aido%2FWalletWatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aido","download_url":"https://codeload.github.com/aido/WalletWatcher/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246009177,"owners_count":20708907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","bitcoin","cryptocurrency","python","security","wallet"],"created_at":"2025-03-28T10:16:10.839Z","updated_at":"2026-04-18T17:03:50.852Z","avatar_url":"https://github.com/aido.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e \u003cimg src=\"assets/icons/wallet.svg\" alt=\"Wallet Watcher\" width=\"15%\" height=\"15%\"\u003e\u003c/p\u003e\n\n# Wallet Watcher\n\n[![Licence: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CodeQL](https://github.com/aido/WalletWatcher/actions/workflows/codeql.yml/badge.svg)](https://github.com/aido/WalletWatcher/actions/workflows/codeql.yml)\n\nThis project provides a secure method for monitoring the balance of a cold wallet without compromising its security. It utilises a Python script, running on a  Bitcoin Core node, to monitor a read-only wallet created from a cold wallet's xpub, and uses Firebase Cloud Messaging (FCM) to send notifications of balance changes to a mobile phone device.\n\n## Overview\n\nWallet Watcher is divided into two main components:\n\n1.  **Python Script (Server-Side):**\n    * Runs on a personal, secure Bitcoin Core node.\n    * Uses a cold wallet's extended public key (xpub) to create and monitor a read-only wallet on the Bitcoin Core node.\n    * Periodically checks the balance of the created wallet using the Bitcoin Core node's `getbalance` RPC call.\n    * Sends notifications to a mobile phone device on balance changes.\n    * Sends a \"heartbeat\" notification every 24 hours to confirm the script is running.\n    * Sends a notification if the script is shutdown.\n    * See the [Python README](python/README.md) for detailed instructions.\n2.  **Lightweight Android App (Client-Side):**\n    * Receives notifications about balance changes and script status on a mobile phone device.\n    * Its sole purpose is to receive and present notifications from the server-side Python script.\n    * See the [Android README](android/README.md) for detailed instructions.\n\n## Functionality\n\n* **Cold Wallet Monitoring:** The Python script utilises a cold wallet's xpub to create a read-only wallet on the Bitcoin Core node, enabling balance monitoring without compromising the cold wallet's security.\n* **Real-time Balance Monitoring:** The Python script continuously monitors the Bitcoin wallet's balance.\n* **Change Notifications:** When a balance change is detected, a notification is sent to the mobile phone device.\n* **Heartbeat Notifications:** A regular heartbeat notification confirms the script's operational status.\n* **Shutdown Notifications:** A notification is sent if the script is stopped, ensuring awareness of monitoring interruptions.\n\n## Security\n\n* **Minimal Data Exposure:** Notifications on mobile device only indicate a balance change or script status, minimizing potential information leakage. Notifications indicate just that a balance change event has occured and do not contain the balance amount.\n* **No Wallet Information on Mobile Phone Device:** The mobile phone device never stores any private keys, xpubs, or any other wallet information. If the device is lost or compromised, the wallet remains completely secure, and **even the wallet's existence and balance are unknown to the phone.**\n* **Ephemeral Notifications:** Notifications are designed to be short-lived, minimizing the window of potential data exposure. They are intended for immediate alerts and do not persist on the mobile device.\n* **No Wallet Information Shared with Third Parties:** The Python script and Bitcoin Core node run on a personal, secure server, ensuring that no wallet information (xpubs and balances) is shared with any third party.\n* **Personal Server:** All wallet data is kept on a personal, secure server, preventing any third-party access to the sensitive information.\n* **Cold Wallet Security:** The use of xpubs to create a read-only wallet on the Bitcoin Core node allows for balance monitoring without compromising the security of cold wallets. Because xpubs are used, the wallet is \"read-only,\" and no funds can be moved.\n* **Node Security:** The security of the Bitcoin Core node and the Python script's execution environment is paramount. Ensure the server is properly secured with firewalls, access controls, and up-to-date software.\n* **RPC Authentication:** Strong RPC credentials are essential to prevent unauthorised access to the Bitcoin Core node.\n* **Firebase Cloud Messaging Security:** FCM provides secure communication channels. Ensure your FCM project is configured with appropriate security measures.\n\n## Connectivity Diagram\n\nHere's a diagram illustrating the connectivity between the various components:\n\n```mermaid\ngraph TB\n    1[\"fa:fa-wallet Cold Wallet\"] --\u003e|xpub| 2.1;\n    subgraph 2[\"fa:fa-server Secure Server\"]\n        2.1[\"fa:fa-bitcoin-sign Bitcoin Core Node\"]\n        2.2[\"fa:fa-python Wallet Watcher Python Script\"];\n    end\n    subgraph 3[\"fa:fa-cloud Cloud\"]\n        3.1[\"fa:fa-server Firebase Cloud Messaging\"];\n        3.2(fa:fa-database Firestore Database):::database\n    end\n    subgraph 4[\"fa:fa-mobile-screen-button Mobile Device\"]\n        4.1[\"fa:fa-android Wallet Watcher App\"];\n    end\n    2.1 \u003c--\u003e|RPC| 2.2\n    2.2 \u003c--\u003e|RPC| 3.1;\n    2.2 \u003c--\u003e|RPC| 3.2;\n    3.1 --\u003e|Notification| 4.1;\n    3.2 \u003c--\u003e|Token| 4.1;\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a pull request.\n\n## Licence\n\nThis project is licensed under the MIT Licence - see the [LICENCE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faido%2Fwalletwatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faido%2Fwalletwatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faido%2Fwalletwatcher/lists"}