Direct Integration with Bitcoin

Fwiw, I have pinged folks on the BTC project to take a look.


That error appears to come from bitcoin-integration-demo/src/bitcoin_integration_demo at master · ielashi/bitcoin-integration-demo · GitHub. So maybe calling the actual bitcoin_send_transaction of the management canister would be okay.

I’m actually not sure if there is a limit implementation wise. Maybe @ielashi can better speak of this topic.


Awesome work @spnrapp! As @PaulLiu mentioned, the error you’re seeing here is an error from the demo canister that I had published, which was meant to be for demo purposes only and not production use.

Instead of using that, you should instead use the management canister API directly, just like I’m doing in the source code of that example, and that API doesn’t have the 1,000-byte limit.


Thanks, @PaulLiu and @ielashi. That explains it. We misread your example code.

Does the actual API impose a limit at all? Or is it just relying on cycle fee per byte?

1 Like

The API itself poses no limit. However, there is a practical limit of 2MiB, since that is the maximum size of an inter-canister request on the IC currently.


Hi there,

I am removing your comment because it is off-topic

Ok, I will paraphrase

ICP/BTC transactions are too large and signed transactions necessary for defi don’t work?

1 Like

Not sure I follow. Are you referring to the thread above about signed transactions? Maybe I’m misreading something, but you can see the issue was resolved (3rd party developer accidentally misread something… something we have all done) and then dev fixed it.


This is awesome!

I recall your Supernova presentation when you showed the developer preview integration – I was looking forward to the “real” integration already then. :slight_smile:

Great work!


Can someone familiar with Stacks ( explain how it is different (not technically, but rather practically) from the IC native integration? It seems eerily similar…


This is a very solid article that answers these questions IC&BTC Integration 02: Differences From Other Cross-chain Integrated BTC Solutions

1 Like

FYI folks:

Docs and sample dapps are live for the testnet:


Stacks, as far as I can recall, uses over-collateralisation bring BTC on chain. So every BTC on the network should be backed by an equal amount of STX.

Practically also, I am not sure if the smart contracts can send real BTC. STX can read the BTC blockchain but it doesn’t have anything like the threshold ECDSA needed to send BTC transactions, so the applications using BTC seem to be more limited to things like atomic swaps.


When I test the interface locally, it failed:

I started the bitcoind, and:

dfx --version
dfx 0.11.1

dfx replica --enable-bitcoin --bitcoin-node

~/.cache/dfinity/versions/0.11.1/icx-proxy \
    --fetch-root-key \
    --address \
    --replica http://localhost:8080

dfx canister call basic_bitcoin get_balance '("mijgLqRdTmiRVUW4aYHG5myWBmnPvXPQuU")'
Error: Failed update call.
Caused by: Failed update call.
  The Replica returned an error: code 5, message: "Canister rwlgt-iiaaa-aaaaa-aaaaa-cai trapped explicitly: Panicked at 'called `Result::unwrap()` on an `Err` value: (CanisterReject, "The bitcoin API is not enabled on this subnet.")', src/basic_bitcoin/src/"

According to The bitcoin API is not enabled on this subnet., what is wrong with my startup command of dfx replica?

From what I know, ThorChain is closest of all chains out there to what the IC is doing in terms of integration with other chains. It uses also a native integration where they run a full node of the target blockchain per node to do the protocol level integration which we did with an adapter and a lightweight node. They also use threshold ECDSA, but they use a scheme that has the following drawbacks in contrast to ours:

  • Their protocol relies on a synchronous network assumption, which does not reflect reality of communication networks
  • A dishonest node can make the signing protocol fail, while the IC protocol degrades gracefully in such a case

Looks like a dfx bug to me. @ericswanson is best equipped to figure this out.

@flyq, can you try two things for me, please?

  1. try the same with dfx start instead of dfx replica
  2. try configuring the same information through dfx.json. The syntax should be like this:
"defaults": {
  "bitcoin": {
    "enabled": true,
    "nodes": [""]
1 Like

In addition to what @Severin mentioned, you need dfx 0.11.1-beta.2 or later. I’d suggest you look at the sample code to see how to set up your project.


After changed from dfx replica to dfx start and added bitcoin to dfx.json config, it works. the dfx version is 0.11.1

1 Like

I briefly looked into Stacks to provide a response to your question, and the result is pretty underwhelming considering the current situation of Stacks.

Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using c32check) and query the Bitcoin network.

See below image:

Decidable language - Clarity contracts have direct visibility into Bitcoin state.(1)
(1) More work needed to realize the future vision. In particular, Clarity contract can’t write back to Bitcoin (yet)

If this 3rd-party information is correct, this would mean that Stacks does not have true Bitcoin smart contracts, at least not yet. And there is no information to be found on how they would do it. The main point where Bitcoin comes in is that Stacks uses Bitcoin as a base layer for securing its own chain, which means they suffer from the same finality times as Bitcoin, but at least have much greater throughout thanks to microblocks in between the anchor blocks that correspond to Bitcoin blocks. But this means major implications on how to write smart contracts as you don’t have the 1s finality as on the IC, but that of Bitcoin. Their mechanism of using Bitcoin as a base layer to secure their chain gives their smart contracts visibility into the Bitcoin state, but without write access, so they can trigger actions based on what happens on Bitcoin, but that’s it.

To me, this is pretty underwhelming in terms of Bitcoin DeFi, essentially, there’s no true Bitcoin smart contracts at this time in Stacks, but they can only use Bitcoin information to trigger actions in the smart contracts on Stacks.

Hope that helps.