{"id":30703156,"url":"https://github.com/dfinity/bitcoin-developer-preview","last_synced_at":"2025-09-02T16:56:28.054Z","repository":{"id":38329606,"uuid":"453932265","full_name":"dfinity/bitcoin-developer-preview","owner":"dfinity","description":"A preview of the integration between Bitcoin and the Internet Computer.","archived":false,"fork":false,"pushed_at":"2025-08-27T11:53:10.000Z","size":41060,"stargazers_count":39,"open_issues_count":3,"forks_count":11,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-08-27T20:51:12.755Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","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/dfinity.png","metadata":{"files":{"readme":"README.adoc","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,"zenodo":null}},"created_at":"2022-01-31T08:40:15.000Z","updated_at":"2025-08-27T11:53:15.000Z","dependencies_parsed_at":"2024-10-29T09:44:34.609Z","dependency_job_id":null,"html_url":"https://github.com/dfinity/bitcoin-developer-preview","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dfinity/bitcoin-developer-preview","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fbitcoin-developer-preview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fbitcoin-developer-preview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fbitcoin-developer-preview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fbitcoin-developer-preview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dfinity","download_url":"https://codeload.github.com/dfinity/bitcoin-developer-preview/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dfinity%2Fbitcoin-developer-preview/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273317765,"owners_count":25084037,"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","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-09-02T16:56:26.248Z","updated_at":"2025-09-02T16:56:28.033Z","avatar_url":"https://github.com/dfinity.png","language":"Rust","readme":"= Bitcoin Integration Developer Preview\n\n== Overview\n\nThe https://dfinity.org/howitworks/direct-integration-with-bitcoin[integration]\nbetween the Internet Computer and Bitcoin will enable developers to build canisters that:\n\n1. *Securely own Bitcoin.*\n+\nCanisters will be able to have the Internet Computer securely create ECDSA keys\nfor them via a threshold ECDSA protocol so that they can own Bitcoin.\n\n2. *Interact with the Bitcoin network.*\n+\nCanisters will be able to send transactions, get transaction outputs, as well as\nget the balance of any Bitcoin address.\nThe aforementioned threshold ECDSA protocol is used to securely sign transactions.\n\n== Differences to Main Release\n\nThe developer preview enables developers to work with the Bitcoin integration features\nbefore the proper launch.\n\nIn the developer preview, all components run *locally*, i.e., no Bitcoin functionality\nis deployed on mainnet.\nThe Bitcoin canister is configured to interact with a local Bitcoin network in `regtest` mode.\n\nBy contrast, the Bitcoin functionality will be exposed through the\nhttps://smartcontracts.org/docs/interface-spec/index.html#ic-management-canister[management canister]\non mainnet.\n\nThe Bitcoin API on mainnet will be quite similar to the \u003c\u003ccanister/README.adoc#API,API\u003e\u003e\nin the developer preview.\nHowever, the function signatures will be slightly different. Moreover, the Bitcoin\nfunctionality will be extended, for example, by offering an API for fee management.\n\n== Components\n\nThe developer preview consists of the following components:\n\n1. *The Bitcoin Canister*\n+\nThe Bitcoin canister provides the API that developers can use to interact with the Bitcoin networks.\n\n+\nSee the `./canister` directory for more details.\n\n2. *An Example Project*\n+\nThe project showcases how developers can achieve the following:\n\n. Get the balance of a Bitcoin address.\n. Get transaction outputs and use them to build a transaction.\n. Sign a transaction and send it to the Bitcoin network.\n\n+\nSee the `./example` directory for more details.\n\nNOTE: The developer preview focuses strictly on the interaction with the Bitcoin network.\nSecurely generating ECDSA keys is beyond the scope of the developer preview.\n\n== Getting Started\n\nWith the developer preview you'll be able to setup a local Bitcoin network and interact with\nthat network using canisters.\n\nThere are two ways to set up:\n\n. \u003c\u003cmanual-setup\u003e\u003e\n. \u003c\u003cdocker-setup\u003e\u003e\n\n== Manual Setup\n=== Prerequisites\n\n* https://rustup.rs/[Rust]\n* https://smartcontracts.org/docs/download.html[dfx] \u003e= 0.8.4\n* https://bitcoin.org/en/download[Bitcoin Core]. Mac users are recommended to download the `.tar.gz` version.\n* Mac users need to install https://brew.sh/[homebrew] and then use it to install additional packages by running `brew install llvm binaryen cmake`\n\nNOTE: These instructions assume you're running Linux or MacOS. We do not officially support Windows.\n\nThe first step would be to setup a local Bitcoin network.\n\n=== Setting up a local Bitcoin network\n\n1. Unpack the `.tar.gz` file.\n2. Create a directory named `data` inside the unpacked folder.\n3. Create a file called `bitcoin.conf` at the root of the unpacked folder and add the following contents:\n+\n```\n# Enable regtest mode. This is required to setup a private bitcoin network.\nregtest=1\n\n# Dummy credentials that are required by `bitcoin-cli`.\nrpcuser=btc-dev-preview\nrpcpassword=Wjh4u6SAjT4UMJKxPmoZ0AN2r9qbE-ksXQ5I2_-Hm4w=\nrpcauth=btc-dev-preview:8555f1162d473af8e1f744aa056fd728$afaf9cb17b8cf0e8e65994d1195e4b3a4348963b08897b4084d210e5ee588bcb\n```\n4. Run `bitcoind` to start the bitcoin client using the following command:\n+\n`./bin/bitcoind -conf=$(pwd)/bitcoin.conf -datadir=$(pwd)/data`\n\n5. Create a wallet: `./bin/bitcoin-cli -conf=$(pwd)/bitcoin.conf createwallet mywallet`\n+\nIf everything is setup correctly, you should see the following output:\n+\n```\n{\n  \"name\": \"mywallet\",\n  \"warning\": \"\"\n}\n```\n\n6. Generate a bitcoin address and save it in variable for later reuse:\n+\n```\nexport BTC_ADDRESS=$(./bin/bitcoin-cli -conf=$(pwd)/bitcoin.conf getnewaddress)\n```\n+\nThis will generate a bitcoin address for your wallet to receive funds.\n\n7. Mine blocks to receive some Bitcoin as a reward.\n+\n`./bin/bitcoin-cli -conf=$(pwd)/bitcoin.conf generatetoaddress 101 $BTC_ADDRESS`\n+\nYou should see an output that looks similar to, but not exactly like, the following:\n+\n```\n[\n  \"1625281b2595b77276903868a0fe2fc31cb0c624e9bdc269e74a3f319ceb48de\",\n  \"1cc5ba7e86fc313333c5448af6c7af44ff249eca3c8b681edc3c275efd3a2d38\",\n  \"1d3c85b674497ba08a48d1b955bee5b4dc4505ffe4e9f49b428153e02e3e0764\",\n  ...\n  \"0dfd066985dc001ccc1fe6d7bfa53b7ad4944285dc173615792653bbd52151f1\",\n  \"65975f1cd5809164f73b0702cf326204d8fee8b9669bc6bd510cb221cf09db5c\",\n]\n```\n\n=== Running the IC-Bitcoin Adapter\n\nNow that bitcoin is setup locally, it is time to run the IC-Bitcoin adapter.\n\nThe IC-Bitcoin adapter is a process that fetches headers and blocks from the Bitcoin network\nand passes them into the Internet Computer. The ic-bitcoin adapter will be integrated into the\nreplica with the main release. For the developer preview, it needs to be launched separately.\n\nRun the following commands to download, build, and run the adapter.\n\n```bash\n# clone the ic repository and checkout a specific commit.\ngit clone https://github.com/dfinity/ic.git\ncd ic\ngit checkout 99116f8e872b8765aa609f91eb8c9394914c483d\n\n# Move into the rs directory and run the adapter.\ncd rs\ncargo run --bin ic-btc-adapter -- ./bitcoin/adapter/tests/sample/regtest.config.json\n```\n\n[[Deploying-the-Bitcoin-Canister]]\n=== Deploying the Bitcoin Canister\n\nWith `bitcoind` and the adapter running, we can now run a local replica with the Bitcoin canister.\n\n1. Clone this repository.\n2. From the root directory of the repository, start the local replica.\n+\n```bash\ndfx start --clean --background\n```\n3. Deploy the Bitcoin canister to the local replica in regtest mode.\n+\n```\ndfx deploy btc --no-wallet\n```\n\n=== Running the Adapter Shim\n\nThe shim is the final piece that needs to be started up.\n\nFrom this repository, run the following command:\n\n```bash\ncargo run --features=\"tokio candid ic-agent garcon tonic tonic-build\" --bin adapter-shim $(dfx canister --no-wallet id btc)\n```\n\nThe shim will start syncing blocks from your local bitcoin setup into the bitcoin canister.\nOnce that's complete, you'll be able to query the bitcoin canister about the bitcoin state.\nSee \u003c\u003cusing-the-bitcoin-canister\u003e\u003e for more details and checkout the \u003c\u003cexamples/README.adoc#example-project,example project\u003e\u003e.\n\n== Docker Setup\n\n=== Prerequisites\n\nInstead of downloading bitcoin and cloning the `ic` repository, this repository offers an alternate\nsolution using Docker and `docker-compose`.\n\n* https://rustup.rs/[Rust]\n* https://smartcontracts.org/docs/download.html[dfx] \u003e= 0.8.4\n* Mac users need to install https://brew.sh/[homebrew] and then use it to install additional packages by running `brew install llvm binaryen cmake`\n* Docker\n** Mac: https://docs.docker.com/desktop/mac/install/[Docker for Mac]\n** Linux: https://docs.docker.com/engine/install/[Docker Engine] and https://docs.docker.com/compose/install/[Docker Compose].\n\n=== Setting up a local Bitcoin network and the IC-Bitcoin Adapter\n\n1. `docker-compose up -d` will start `bitcoind` in the background and begin building a fresh image for the IC-Bitcoin adapter.\n2. Verify that bitcoind is running: `docker-compose exec bitcoind bitcoin-cli -conf=/conf/bitcoin.conf getmininginfo`\n+\nIf everything is setup correctly, you should see the following output:\n+\n```\n{\n  \"blocks\": 0,\n  \"difficulty\": 4.656542373906925e-10,\n  \"networkhashps\": 0,\n  \"pooledtx\": 0,\n  \"chain\": \"regtest\",\n  \"warnings\": \"\"\n}\n```\n\n3. Create a wallet: `docker-compose exec bitcoind bitcoin-cli -conf=/conf/bitcoin.conf createwallet mywallet`\n+\nIf everything is setup correctly, you should see the following output:\n+\n```\n{\n  \"name\": \"mywallet\",\n  \"warning\": \"\"\n}\n```\n\n4. Generate a bitcoin address and save it in variable for later reuse:\n+\n```\nexport BTC_ADDRESS=$(docker-compose exec bitcoind bitcoin-cli -conf=/conf/bitcoin.conf getnewaddress | tr -d '\\r')\n```\n+\nThis will generate a bitcoin address for your wallet to receive funds.\n\n5. Mine blocks to receive some Bitcoin as a reward.\n+\n`docker-compose exec bitcoind bitcoin-cli -conf=/conf/bitcoin.conf generatetoaddress 101 $BTC_ADDRESS`\n+\nYou should see an output that looks similar to, but not exactly like, the following:\n+\n```\n[\n  \"1625281b2595b77276903868a0fe2fc31cb0c624e9bdc269e74a3f319ceb48de\",\n  \"1cc5ba7e86fc313333c5448af6c7af44ff249eca3c8b681edc3c275efd3a2d38\",\n  \"1d3c85b674497ba08a48d1b955bee5b4dc4505ffe4e9f49b428153e02e3e0764\",\n  ...\n  \"0dfd066985dc001ccc1fe6d7bfa53b7ad4944285dc173615792653bbd52151f1\",\n  \"65975f1cd5809164f73b0702cf326204d8fee8b9669bc6bd510cb221cf09db5c\",\n]\n```\n6. Verify the adapter is running: `docker-compose logs adapter`\n+\nYou should an output that looks similar to the following:\n```\nadapter_1   | Feb 02 01:01:56.512 INFO Connected to 172.29.0.2:18444\nadapter_1   | Feb 02 01:01:57.022 INFO Received version from 172.29.0.2:18444\nadapter_1   | Feb 02 01:01:57.022 INFO Completed the version handshake with 172.29.0.2:18444\nadapter_1   | Feb 02 01:01:57.022 INFO Adding peer_info with addr : 172.29.0.2:18444\nadapter_1   | Feb 02 01:01:57.223 INFO Received verack from 172.29.0.2:18444\n```\n\nContinue with the Getting Started directions from \u003c\u003cDeploying-the-Bitcoin-Canister, Deploying the Bitcoin Canister\u003e\u003e to complete setup.\n\n=== Viewing `bitcoind` and `IC-Bitcoin Adapter` output\n\n* To view the logs of the `bitcoind` container: `docker-compose logs -f bitcoind`\n* To view the logs of the `adapter` container: `docker-compose logs -f adapter`\n\n== Using the Bitcoin Canister\n\nThere's an example project in the `./example` directory that showcases how to interact with the Bitcoin canister.\nAdditionally, you can call the Bitcoin canister directly using `dfx`. Examples:\n\n**Fetching the balance/UTXOs of an address**\n```\ndfx canister --no-wallet call btc get_balance \"(record { address = \\\"$BTC_ADDRESS\\\"})\"\ndfx canister --no-wallet call btc get_utxos \"(record { address = \\\"$BTC_ADDRESS\\\"})\"\n```\n\n**Fetching the balance/UTXOs of an address with a minimum of 6 confirmations**\n```\ndfx canister --no-wallet call btc get_balance \"(record { address = \\\"$BTC_ADDRESS\\\"; min_confirmations = opt 6})\"\ndfx canister --no-wallet call btc get_utxos \"(record { address = \\\"$BTC_ADDRESS\\\"; min_confirmations = opt 6})\"\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfinity%2Fbitcoin-developer-preview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdfinity%2Fbitcoin-developer-preview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfinity%2Fbitcoin-developer-preview/lists"}