Payjoin persistence by Mshehu5 · Pull Request #242 · bitcoindevkit/bdk-cli

Mshehu5 · 2026-02-16T15:39:28Z

Description

Address #149 also follow up to #200
This PR adds persistance to existing async payjoin integration
This introduces neccessary database model and tables also add commad for resume to allow interrupted sessions to be continued also a particular session either send or receive.
A history commad to view payjoin history and status has been added

Notes to the reviewers

Step to review this include making a payjoin transaction

Run a receiver to get a BIP21 URI then pass it to the sender as seen in docs

bdk-cli/README.md

Lines 121 to 141 in b9cf2ac

    
           To start a Payjoin session as the receiver with regtest RPC and example OHTTP relays: 
        
           ``` 
        
           cargo run --features rpc -- --network regtest wallet --wallet payjoin_wallet1 config --ext-descriptor "wpkh(tprv8ZgxMBicQKsPd2PoUEcGNDHPZmVWgtPYERAwMG6qHheX6LN4oaazp3qZU7mykiaAZga1ZB2SJJR6Mriyq8MocMs7QTe7toaabSwTWu5fRFz/84h/1h/0h/0/*)#8guqp7rn" --client-type rpc --database-type sqlite --url "127.0.0.1:18443"  
        
           cargo run --features rpc -- wallet --wallet payjoin_wallet1 sync 
        
           cargo run --features rpc -- wallet --wallet payjoin_wallet1 balance 
        
           cargo run --features rpc -- wallet --wallet payjoin_wallet1 receive_payjoin --amount 400000 --max_fee_rate 1000 --directory "https://payjo.in" --ohttp_relay "https://pj.bobspacebkk.com" --ohttp_relay "https://pj.benalleng.com" 
        
           ``` 
        
           To send a Payjoin with regtest RPC and example OHTTP relays: 
        
           ``` 
        
           cargo run --features rpc -- --network regtest wallet --wallet payjoin_wallet2 config --ext-descriptor "wpkh(tprv8ZgxMBicQKsPfBxswkATvZRQ9kDdRbJPtHYZaZCARL2myxcK7DqsqPhRo2G2rRVHFPbowq63BE6S4k2pUMYeF2fUMTT63Q7zhoXtKsM1FaS/84'/1'/0'/0/*)#qf5gnqrf" --client-type rpc --database-type sqlite --url "127.0.0.1:18443"  
        
           cargo run --features rpc -- wallet --wallet payjoin_wallet2 sync 
        
           cargo run --features rpc -- wallet --wallet payjoin_wallet2 balance 
        
           cargo run --features rpc -- wallet --wallet payjoin_wallet2 send_payjoin --ohttp_relay "https://pj.bobspacebkk.com" --ohttp_relay "https://pj.benalleng.com" --fee_rate 1 --uri "<URI>" 
        
           ```

To test resumption, interrupt either side with Ctrl+C mid-session then run resume on that side to continue. A few scenarios worth covering: receiver resuming after interrupt and sender resuming after interrupt. Use history after each scenario to confirm the session state was persisted correctly.

docs for this can be seen in 7e4ffd1

Checklists

All Submissions:

I've signed all my commits
I followed the contribution guidelines
I ran cargo fmt and cargo clippy before committing

New Features:

I've added docs for the new feature

coveralls · 2026-02-16T15:44:36Z

Pull Request Test Coverage Report for Build 22068931916

Details

0 of 763 (0.0%) changed or added relevant lines in 5 files are covered.
5 unchanged lines in 3 files lost coverage.
Overall coverage decreased (-1.9%) to 8.848%

Changes Missing Coverage	Changed/Added Lines	%
src/error.rs	21	0.0%
src/utils.rs	22	0.0%
src/handlers.rs	50	0.0%
src/payjoin/db.rs	262	0.0%
src/payjoin/mod.rs	408	0.0%

Files with Coverage Reduction	New Missed Lines	%
src/utils.rs	1	0.0%
src/handlers.rs	2	12.81%
src/payjoin/mod.rs	2	0.0%

Totals
Change from base Build 21153868360:	-1.9%
Covered Lines:	268
Relevant Lines:	3029

💛 - Coveralls

- Create db.rs with Database, SenderPersister and ReceiverPersister - Implement SessionPersister trait for both sender and receiver - Add session ID management and query methods - Add input deduplication tracking to prevent probing attacks - Add timestamp formatting utilities

- Add database initialization in handlers - Replace NoopSessionPersister with real persisters - Implement session resumption for existing sessions - Add input-seen-before tracking in receiver flow - Remove verbose error wrapping (use ? operator)

- Implement resume_payjoins() to continue pending sessions - Add history() to display all session states - Add session status text helpers for UI display - Support filtering by session ID

- Document resume and history commands - Add sqlite dependecy for payjoin

tvpeter

Thank you @Mshehu5 for working on this feature.

Below are some of the observations that I think will make the implementation better:

I noticed that the implementation used only the sqlite db, and since sqlite is a db option in the project, I think it will be ideal if you also include implementation for redb db so users are free to choose any to use.
The implementation does not provide for pruning/cleanup of data. Given that the db will tend to grow linearly and become sizable over time, I think it will be great to consider adding a pruning subcommand or mechanism that deletes irrelevant data.
Since the save_event is generated at multiple transitions in a session, I think it will be great if you consider grouping such updates in a db transaction to ensure that entries are saved successfully.

I have also left some comments in the code.

Thank you.

tvpeter · 2026-03-11T18:47:23Z

src/handlers.rs

+) -> Result<std::sync::Arc<crate::payjoin::db::Database>, Error> {
+    use crate::payjoin::db::{DB_FILENAME, Database};
+    let home_dir = prepare_home_dir(datadir)?;
+    let db_path = home_dir.join(DB_FILENAME);


I think it will be more reasonable if the db path includes the specific wallet that is used instead of having the payjoin db at the directory level

tvpeter · 2026-03-11T18:48:30Z

src/handlers.rs

    }
 }

+#[cfg(feature = "payjoin")]


Since sqlite is also a feature, this should be available only when both sqlite and payjoin features are enabled

tvpeter · 2026-03-11T18:49:07Z

src/handlers.rs

 }

+#[cfg(feature = "payjoin")]
+pub fn open_payjoin_db(


The fn will be more suitable in the utils file

tvpeter · 2026-03-11T19:01:12Z

src/payjoin/mod.rs

+            send_session_ids.retain(|id| id.as_i64() == session_id);
+
+            if recv_session_ids.is_empty() && send_session_ids.is_empty() {
+                return Ok(serde_json::to_string_pretty(&json!({


Instead of erroring out when no session id is provided, I think it will be a better flow to select the most recent session id and resume that session.

github-project-automation bot added this to BDK-CLI Feb 16, 2026

notmandatory moved this to In Progress in BDK-CLI Feb 18, 2026

notmandatory assigned Mshehu5 Feb 18, 2026

Mshehu5 changed the title ~~Payjoin persistance~~ Payjoin persistence Feb 21, 2026

Mshehu5 force-pushed the payjion_persistance branch from 7e4ffd1 to ef73b66 Compare February 24, 2026 05:38

Mshehu5 marked this pull request as ready for review February 24, 2026 05:41

Mshehu5 mentioned this pull request Feb 24, 2026

Standup Input: Week of 2026-02-23 payjoin/rust-payjoin#1352

Closed

Mshehu5 force-pushed the payjion_persistance branch 3 times, most recently from ce0d5d9 to a5e2482 Compare February 24, 2026 11:35

Mshehu5 added 3 commits February 24, 2026 13:55

feat: add resume and history commands for payjoin sessions

a676d69

- Implement resume_payjoins() to continue pending sessions - Add history() to display all session states - Add session status text helpers for UI display - Support filtering by session ID

docs: update README with new payjoin session commands

c79bd95

- Document resume and history commands - Add sqlite dependecy for payjoin

Mshehu5 force-pushed the payjion_persistance branch from a5e2482 to c79bd95 Compare February 24, 2026 12:57

tvpeter added this to the CLI 3.0.0 milestone Feb 26, 2026

tvpeter requested changes Mar 11, 2026

View reviewed changes

tvpeter removed this from the CLI 3.0.0 milestone Mar 12, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Payjoin persistence#242

Payjoin persistence#242
Mshehu5 wants to merge 4 commits intobitcoindevkit:masterfrom
Mshehu5:payjion_persistance

Mshehu5 commented Feb 16, 2026 •

edited

Loading

Uh oh!

coveralls commented Feb 16, 2026

Uh oh!

tvpeter left a comment

Uh oh!

tvpeter Mar 11, 2026

Uh oh!

tvpeter Mar 11, 2026

Uh oh!

tvpeter Mar 11, 2026

Uh oh!

tvpeter Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	To start a Payjoin session as the receiver with regtest RPC and example OHTTP relays:

	```
	cargo run --features rpc -- --network regtest wallet --wallet payjoin_wallet1 config --ext-descriptor "wpkh(tprv8ZgxMBicQKsPd2PoUEcGNDHPZmVWgtPYERAwMG6qHheX6LN4oaazp3qZU7mykiaAZga1ZB2SJJR6Mriyq8MocMs7QTe7toaabSwTWu5fRFz/84h/1h/0h/0/*)#8guqp7rn" --client-type rpc --database-type sqlite --url "127.0.0.1:18443"

	cargo run --features rpc -- wallet --wallet payjoin_wallet1 sync
	cargo run --features rpc -- wallet --wallet payjoin_wallet1 balance

	cargo run --features rpc -- wallet --wallet payjoin_wallet1 receive_payjoin --amount 400000 --max_fee_rate 1000 --directory "https://payjo.in" --ohttp_relay "https://pj.bobspacebkk.com" --ohttp_relay "https://pj.benalleng.com"
	```

	To send a Payjoin with regtest RPC and example OHTTP relays:

	```
	cargo run --features rpc -- --network regtest wallet --wallet payjoin_wallet2 config --ext-descriptor "wpkh(tprv8ZgxMBicQKsPfBxswkATvZRQ9kDdRbJPtHYZaZCARL2myxcK7DqsqPhRo2G2rRVHFPbowq63BE6S4k2pUMYeF2fUMTT63Q7zhoXtKsM1FaS/84'/1'/0'/0/*)#qf5gnqrf" --client-type rpc --database-type sqlite --url "127.0.0.1:18443"

	cargo run --features rpc -- wallet --wallet payjoin_wallet2 sync
	cargo run --features rpc -- wallet --wallet payjoin_wallet2 balance

	cargo run --features rpc -- wallet --wallet payjoin_wallet2 send_payjoin --ohttp_relay "https://pj.bobspacebkk.com" --ohttp_relay "https://pj.benalleng.com" --fee_rate 1 --uri "<URI>"
	```

Conversation

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

Uh oh!

Description

Notes to the reviewers

Checklists

All Submissions:

New Features:

Uh oh!

coveralls commented Feb 16, 2026

Pull Request Test Coverage Report for Build 22068931916

Details

💛 - Coveralls

Uh oh!

tvpeter left a comment

Choose a reason for hiding this comment

Uh oh!

tvpeter Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

tvpeter Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

tvpeter Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

tvpeter Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Mshehu5 commented Feb 16, 2026 •

edited

Loading