{"id":13612642,"url":"https://github.com/square/beancounter","last_synced_at":"2025-04-13T12:32:26.108Z","repository":{"id":37549481,"uuid":"150627472","full_name":"square/beancounter","owner":"square","description":"Utility to audit the balance of Hierarchical Deterministic (HD) wallets. Supports multisig + segwit wallets.","archived":true,"fork":false,"pushed_at":"2023-02-27T17:59:51.000Z","size":2065,"stargazers_count":145,"open_issues_count":21,"forks_count":20,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-08-02T20:44:30.433Z","etag":null,"topics":["audit","bip32","bitcoin","crypto","cryptocurrency","wallet"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/square.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-09-27T17:58:45.000Z","updated_at":"2024-06-03T17:16:48.000Z","dependencies_parsed_at":"2023-01-19T12:32:46.278Z","dependency_job_id":"cbe592f7-9567-4579-831f-2eecbb962aae","html_url":"https://github.com/square/beancounter","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/square%2Fbeancounter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/square%2Fbeancounter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/square%2Fbeancounter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/square%2Fbeancounter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/square","download_url":"https://codeload.github.com/square/beancounter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223585456,"owners_count":17169303,"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":["audit","bip32","bitcoin","crypto","cryptocurrency","wallet"],"created_at":"2024-08-01T20:00:32.659Z","updated_at":"2024-11-07T20:31:22.743Z","avatar_url":"https://github.com/square.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"Beancounter\n==========\n\n[![license](http://img.shields.io/badge/license-apache_2.0-blue.svg?style=flat)](https://raw.githubusercontent.com/square/beancounter/master/LICENSE) [![travis](https://img.shields.io/travis/com/square/beancounter.svg?maxAge=3600\u0026logo=travis\u0026label=travis)](https://travis-ci.com/square/beancounter)\n[![coverage](https://coveralls.io/repos/github/square/beancounter/badge.svg?branch=master)](https://coveralls.io/r/square/beancounter) [![report](https://goreportcard.com/badge/github.com/square/beancounter)](https://goreportcard.com/report/github.com/square/beancounter)\n\nBeancounter is a command line utility to audit the balance of [Hierarchical Deterministic (HD)][bip32] wallets at a given point in time (or block height). The tool is designed to scale and work for wallets with a large number of addresses or a large number of transactions, with support ranging from simple watch wallets to more complicated multisig + segwit. If you're curious, [here's why we decided to write Beancounter](WHY.md) in the first place.\n\nBeancounter currently supports two types of backends to query the blockchain:\n1. Electrum public servers. When using these servers, Beancounter behaves in a similar fashion to an Electrum client wallet. The servers are queried for transaction history for specific addresses. Using Electrum servers is easiest but requires trusting public servers to return accurate information. There is also potential privacy exposure.\n\n2. Private Btcd node. Btcd is a Bitcoin full node which implements transaction indexes. Setting up a Btcd node can take some time (the initial sync takes ~7 days) and requires maintaining the node up-to-date. The benefit is however a higher level of guarantee that the transaction history is accurate.\n\n![logo](https://raw.githubusercontent.com/square/beancounter/master/coffee.jpg)\n\n[bip32]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki\n\nGetting Started\n===============\n\nInstalling\n----------\nRequires Go 1.11 or higher.\n\n```\n$ git clone https://github.com/square/beancounter/\n$ cd beancounter\n$ go build -mod=vendor\n```\n\nDeriving the child pubkey\n-------------------------\nLet's imagine we want to track the balance of `tpubD8L6UhrL8ML9...` and the derivation being used is `m/1'/1234/change/index`.\n\nWe need to manually perform the `1234` derivation:\n\n```\n$ ./beancounter keytree 1234\nEnter pubkey #1 out of #1:\ntpubD8L6UhrL8ML9Ao47k4pmdvUoiA6QUJVzrJ9BXLgU9idRKnvdRFGgjcxmVxojWGvCcjMi6QWCp8uMpCwWdSFRDNJ7utizxLy27sVWXQT4Jz7\nChild pubkey #1: tpubDBrCAXucLxvjC9n9nZGGcYS8pk4X1N97YJmUgdDSwG2p36gbSqeRuytHYCHe2dHxLsV2EchX9ePaFdRwp7cNLrSpnr3PsoPLUQqbvLBDWvh\n```\n\nWe can then use `tpubDBrCAXucLxvj...` to compute the balance.\n\nCompute balance of a HD wallet (using Electrum)\n-----------------------------------------------\n```\n$ ./beancounter compute-balance --type multisig --block-height 1438791\nEnter pubkey #1 out of #1:\ntpubDBrCAXucLxvjC9n9nZGGcYS8pk4X1N97YJmUgdDSwG2p36gbSqeRuytHYCHe2dHxLsV2EchX9ePaFdRwp7cNLrSpnr3PsoPLUQqbvLBDWvh\n...\nBalance: 267893477\n```\n\nCompute balance of a single address (using Electrum)\n----------------------------------------------------\n```\n$ ./beancounter compute-balance --type single-address --lookahead 1 --block-height 1438791\nEnter single address:\nmzoeuyGqMudyvKbkNx5dtNBNN59oKEAsPn\n...\nBalance: 111168038\n```\n\nCompute balance of a HD wallet (using Btcd)\n-------------------------------------------\n\n[https://github.com/btcsuite/btcd](https://github.com/btcsuite/btcd) contains information on how to setup a node.\n\nBeancounter requires `addrindex=1`, `txindex=1`, and `notls=1`. If your node is on a remote server,\nwe recommend tunneling the RPC traffic over ssh or some other secure tunnel.\n\n```\nrpcuser=mia\nrpcpass=ilovebrownies\nrpclisten=127.0.0.1:8334\nnotls=1\n\nblocksonly=1\naddrindex=1\ntxindex=1\n```\n\nOnce the Btcd is up and running, you can do:\n```\n$ ./beancounter compute-balance --type multisig --block-height 1438791 --backend btcd --addr localhost:8334 --rpcuser mia --rpcpass ilovebrownies\nEnter pubkey #1 out of #1:\ntpubDBrCAXucLxvjC9n9nZGGcYS8pk4X1N97YJmUgdDSwG2p36gbSqeRuytHYCHe2dHxLsV2EchX9ePaFdRwp7cNLrSpnr3PsoPLUQqbvLBDWvh\n...\nBalance: 267893477\n```\n\nDetails\n=======\n\nBeancounter is implemented in Go. We picked Go because we wanted an easy build and distribution process. We appreciate the ability to cross-compile and distribute static binaries which don't have external dependencies.\n\nWe use the following process to determine a deterministic wallet's balance at a given block height:\n\n1. Derive external (receive) and internal (change) addresses.\n2. For each address, query the backend for a list of transactions. We keep deriving additional addresses until we find a large number of unused addresses.\n3. Prune the transaction list to remove transactions newer than the block height.\n4. For each transaction, query the backend for the raw transaction.\n5. For each transaction, track whether the output belongs to the wallet and whether\n   it got spent.\n6. Iterate over the transactions and compute the final balance.\n\nContributing\n============\n\nWe appreciate any pull request which fixes bugs or adds features!\n\nIf you need ideas on how to contribute, we would enjoy a 3rd backend (Bitcoin-core based, processing\neach block by streaming the entire blockchain) as well as additional wallet types (e.g. multisig non-segwit).\n\nAdditional unittests and improvements to comments/docs are also always welcome.\n\nLicense\n=======\n\n    Copyright 2018 Square, Inc.\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquare%2Fbeancounter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquare%2Fbeancounter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquare%2Fbeancounter/lists"}