WIP: Create an async corepc-client (adding async support to jsonrpc) by jamillambert · Pull Request #505 · rust-bitcoin/corepc

jamillambert · 2026-02-12T18:26:34Z

Not a merge candidate. Proof of concept only.

This is PR option 1 of 2, both add an async corepc-client but in a slightly different ways. This version adds async support to jsonrpc, the other adds the required part of jsonrpc into corepc-client (#506).

The patches are structured to make it easier to see what was changed from sync to async. First the sync version is copied and renamed, then in a separate patch it is changed to async.

tcharding · 2026-02-16T02:57:17Z

jsonrpc/src/client_async.rs

    /// Creates a new client with the given transport.
-    pub fn with_transport<T: Transport>(transport: T) -> Client {
-        Client { transport: Box::new(transport), nonce: atomic::AtomicUsize::new(1) }
+    pub fn with_transport<T: AsyncTransport>(transport: T) -> AsyncClient {


My suggestion would be to not rename these types. That way the diff is smaller. I'd rename client.rs to client_sync.rs. You'll need to remove the public re-exports from lib.rs and that maybe fix up some paths to always use client_sync:: or client_async:: as appropriate.

tcharding · 2026-02-16T03:00:40Z

jsonrpc/Cargo.toml

+# A transport that uses `bitreq` as the async HTTP client.
+bitreq_http_async = [ "base64", "bitreq", "bitreq/async" ]
+# An async JSON-RPC client implementation.
+client_async = []


Maybe this feature should enable bitreq_http_async?

tcharding · 2026-02-16T03:01:25Z

jsonrpc/Cargo.toml

@@ -22,6 +22,10 @@ default = [ "simple_http", "simple_tcp" ]
 simple_http = [ "base64" ]
 # A transport that uses `bitreq` as the HTTP client.
 bitreq_http = [ "base64", "bitreq" ]


Maybe this should be re-name to bitreq_http_sync?

tcharding · 2026-02-16T03:03:11Z

@apoelstra whats your take man? Would you be willing to have jsonrpc take changes to be able to use bitreq in an async manner? It obviously smashes the dep tree if --all-features are used.

In preparation for adding the new async client rename the existing sync client, associated feature and fuzz target to have the suffic _sync.

tcharding · 2026-02-20T02:20:05Z

Holla at me if/when you would like some review mate.

In preparation for adding an async client remove the reexports of the sync Client and Transport. Fix the affected imports and Debug impl.

Code copy only to make it easier in the next patch to see what the changes are for async.

Remove code related to fuzzing from the new async files. These can be added back later once the async version is working.

In preparation for adding bitreq_http_async feature to jsonrpc move the sync version to the client-sync feature so it is not always on with jsonrpc.

Create a new folder for the upcoming async client and copy in the existing client_sync code. Code copy only to make the next patch easier to review.

Edit the copy of the sync client created in the previous commit to be async. Update the readme and cargo.toml files. Add only small set of RPCs.

Add some vibe coded tests for the async client to check that everything is functional. Tests are for development purposes only to catch simple errors like feature gates etc. and have not been reviewed.

Add a JSONRPC_VERSION constant to remove magic number in code. Add the same version check to batch responses.

Remove the version folders with RPC macros. Rewrite the async client to have the base methods in the main module removing all the macroization. Create a new module for the bdk client that has the required RPCs in it that all return the non-version specific model types. Rewrite the tests to use the bdk client and use a similar structure to the sync tests.

jamillambert · 2026-02-20T15:22:25Z

Rewrote the async client:

Removed all the version folders where the RPC macros were defined.
Removed macroization from client_async module.
Created bdk_client module that implements the the required RPC methods in it using the shared client methods in mod.rs.
- Supports v25 to v30 by checking the server version and then using the required vtype version before converting into the model type.
- The bdk_client RPC methods all return the modelled types. This made the error handling difficult since all of the error types for converting into the modelled type are version specific types. I am not sure how to handle this ergonomically. Currently they all return the same Error type defined in the async client.
- There are a few RPCs that return a single field, e.g. getblock returns a Block and getblockcount a u32. Would it be better to return e.g. Result<u32> instead of Result<GetBlockCount> ?
Rewrote the tests to use the new bdk_client rpc calls.

@tcharding thoughts? in particular the error handling of converting to the modelled type. Returning a modelled type vs the inner field e.g. Block or u32. And having a bdk_client module that only implements the RPCs, the idea was to be able to add another one for e.g. LDK with their required RPCs and arguments but sharing the new, call etc. methods.

tcharding · 2026-02-20T20:12:01Z

client/src/client_async/bdk_client.rs

+    async fn bdk_server_version(&self) -> Result<usize> {
+        let info: serde_json::Value = self.call("getnetworkinfo", &[]).await?;
+        let version = info
+            .get("version")
+            .and_then(serde_json::Value::as_u64)
+            .ok_or(Error::UnexpectedStructure)?;
+        usize::try_from(version).map_err(|_| Error::UnexpectedStructure)


Unfortunately we cannot do this. This is one of the main reasons behind certain design choices in this repo. While it seems sane I heard but cannot remember right now that there may be reasons why a node operator disables the getnetworkinfo method and it shouldn't be relied upon. Sorry for the poor explanation, it was a while ago now and I just committed to memory that we can't rely on it.

I'll comment further near where this is called.

tcharding · 2026-02-20T20:13:57Z

client/src/client_async/bdk_client.rs

+        &self,
+        hash: &BlockHash,
+    ) -> Result<GetBlockHeaderVerbose> {
+        if self.bdk_server_version().await? >= VERSION_WITH_TARGET_FIELD {


Another solution is to do an RPC call to v29 and if the call fails (because the json is mismatched) then try to do a v25 call. There are other solutions I've thought of but this is the one I like most.

This problem is an example of how which versions of Core the client supports effects the logic and how projects might want to do things differently. For example a project that is only hitting a Core node that it controls would not need to do this dance.

I think for this case where there are only two possible versions where one has an extra field trying v29 and if it fails try v25 should work fine.

tcharding · 2026-02-20T20:19:10Z

client/src/client_async/bdk_client.rs

+    pub async fn get_block(&self, hash: &BlockHash) -> Result<GetBlockVerboseZero> {
+        let json: crate::types::v25::GetBlockVerboseZero =
+            self.call("getblock", &[into_json(hash)?, into_json(0)?]).await?;
+        json.into_model().map_err(|e| Error::Returned(e.to_string()))


We don't need to map here. Plain old Ok(json.into_mode()?) works.

tcharding · 2026-02-20T20:51:51Z

Rewrote the async client:

Removed all the version folders where the RPC macros were defined.

Removed macroization from client_async module.

Created bdk_client module that implements the the required RPC methods in it using the shared client methods in mod.rs.

After writing a massive post I realised this solution is not going to work (see bottom for explanation). I think we should inline the bdk module and just document that its designed explicitly with that project in mind.

How about throwing this at the top:

//! Async JSON-RPC client designed explicitly to support BDK.
//!
//! ## Project decisions
//!
//! * Support Core versions 25 to 30.

Supports v25 to v30 by checking the server version and then using the required vtype version before converting into the model type.

Troublesome, commented already on the code.

The bdk_client RPC methods all return the modelled types. This made the error handling difficult since all of the error types for converting into the modelled type are version specific types. I am not sure how to handle this ergonomically. Currently they all return the same Error type defined in the async client.

Another solution is to have an error type for each function. Then it can have a variant (assuming its an enum) for the exact error returned by into_model.

There are a few RPCs that return a single field, e.g. getblock returns a Block and getblockcount a u32. Would it be better to return e.g. Result<u32> instead of Result<GetBlockCount> ?

Agreed that a wrapper type is not useful to returen (eg GetBlockCount). At first blush I think you are correct and returning the inner type is better (its a u64 in this case). After upgrade to bitcoin v0.33 we may have better concrete types to return if needed but your argument stands.

Rewrote the tests to use the new bdk_client rpc calls.

Nice.

@tcharding thoughts? in particular the error handling of converting to the modelled type. Returning a modelled type vs the inner field e.g. Block or u32. And having a bdk_client module that only implements the RPCs, the idea was to be able to add another one for e.g. LDK with their required RPCs and arguments but sharing the new, call etc. methods.

I don't think separation by project module is not going to work because the modules will conflict with each other. And if we feature gate the features will not be additive. We could try some macro stuff but I think it defeats the purpose which is to write a simple clean client that others can fork if they need to.

github-actions bot added C-client C-integration-test C-jsonrpc labels Feb 12, 2026

jamillambert force-pushed the 0212-WIP-client-async branch from d5524e1 to 9a77aa2 Compare February 12, 2026 18:37

jamillambert changed the title ~~WIP: Create an async corepc-client by adding async support to jsonrpc~~ WIP: Create an async corepc-client (adding async support to jsonrpc) Feb 12, 2026

jamillambert mentioned this pull request Feb 12, 2026

WIP: Create an async corepc-client (adding jsonrpc support into the corepc-client crate) #506

Draft

jamillambert force-pushed the 0212-WIP-client-async branch 2 times, most recently from 6981d8f to 6cd8bb2 Compare February 12, 2026 18:53

tnull mentioned this pull request Feb 13, 2026

Clarify stance on corepc-client to be integration-test-only #507

Open

tcharding reviewed Feb 16, 2026

View reviewed changes

Rename jsonrpc sync client and features _sync

a0d7257

In preparation for adding the new async client rename the existing sync client, associated feature and fuzz target to have the suffic _sync.

jamillambert force-pushed the 0212-WIP-client-async branch from 6cd8bb2 to 87dfe15 Compare February 18, 2026 16:58

jamillambert added 9 commits February 20, 2026 14:00

Remove jsonrpc reexports of Client and Transport

64986c4

In preparation for adding an async client remove the reexports of the sync Client and Transport. Fix the affected imports and Debug impl.

Copy jsonrpc client and bitrteq_http for async.

6efe8b9

Code copy only to make it easier in the next patch to see what the changes are for async.

Remove fuzz related sections

a652f85

Remove code related to fuzzing from the new async files. These can be added back later once the async version is working.

Add async support to jsonrpc

2b0664d

Set bitreq_http feature for sync only

681989f

In preparation for adding bitreq_http_async feature to jsonrpc move the sync version to the client-sync feature so it is not always on with jsonrpc.

Copy client_sync to client_async

4ff8dad

Create a new folder for the upcoming async client and copy in the existing client_sync code. Code copy only to make the next patch easier to review.

Make corepc-client async

0d5184d

Edit the copy of the sync client created in the previous commit to be async. Update the readme and cargo.toml files. Add only small set of RPCs.

Vibe code some async tests

d1f0181

Add some vibe coded tests for the async client to check that everything is functional. Tests are for development purposes only to catch simple errors like feature gates etc. and have not been reviewed.

Improve jsonrpc async client

8a9d9f7

Add a JSONRPC_VERSION constant to remove magic number in code. Add the same version check to batch responses.

jamillambert force-pushed the 0212-WIP-client-async branch 3 times, most recently from eb3b27b to 1c174a6 Compare February 20, 2026 15:09

jamillambert force-pushed the 0212-WIP-client-async branch from 1c174a6 to 7a79b87 Compare February 20, 2026 15:09

tcharding reviewed Feb 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

WIP: Create an async corepc-client (adding async support to jsonrpc)#505

WIP: Create an async corepc-client (adding async support to jsonrpc)#505
jamillambert wants to merge 11 commits intorust-bitcoin:masterfrom
jamillambert:0212-WIP-client-async

jamillambert commented Feb 12, 2026 •

edited

Loading

Uh oh!

tcharding Feb 16, 2026

Uh oh!

tcharding Feb 16, 2026

Uh oh!

tcharding Feb 16, 2026

Uh oh!

tcharding commented Feb 16, 2026

Uh oh!

tcharding commented Feb 20, 2026

Uh oh!

jamillambert commented Feb 20, 2026

Uh oh!

tcharding Feb 20, 2026

Uh oh!

tcharding Feb 20, 2026 •

edited

Loading

Uh oh!

jamillambert Feb 20, 2026

Uh oh!

tcharding Feb 20, 2026

Uh oh!

tcharding commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

jamillambert commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tcharding Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

tcharding Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

tcharding Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

tcharding commented Feb 16, 2026

Uh oh!

tcharding commented Feb 20, 2026

Uh oh!

jamillambert commented Feb 20, 2026

Uh oh!

tcharding Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

tcharding Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamillambert Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

tcharding Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

tcharding commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jamillambert commented Feb 12, 2026 •

edited

Loading

tcharding Feb 20, 2026 •

edited

Loading