Repository navigation
Classify Payjoin settlements on the Monitor typestate - #1971
Conversation
Coverage Report for CI Build 42100353006Coverage increased (+0.3%) to 87.778%Details
Uncovered Changes
Coverage Regressions3 previously-covered lines in 1 file lost coverage.
Coverage Stats
💛 - Coveralls |
acc4a2c to
9d7f5b3
Compare
DanGould
left a comment
There was a problem hiding this comment.
My main issues are allow(deprecated) in tests without exercising the new interface where the opportunity exists, deprecating proposal_txid_is_stable for the new behavior, and getting the fallback_txid through #1949 instead of an extra method.
proposal_txid_is_stable can be deprecated here in favor of classify, too. Ignores receiver inputs anyway, which is a problem for actually classifying as stable.
Monitor -> cancel() -> close() writes Aborted after the proposal was posted. Both docs need to drop the "before posting" claim.
5ca8c70 to
3cbff7b
Compare
|
I think I got all follow ups, ready for re-review. |
DanGould
left a comment
There was a problem hiding this comment.
incomplete review, but thoughts that came up while reading rust-bitcoin's policy re: deprecation & versioning
| /// match. When [`expected_payjoin_txid`](Monitor::expected_payjoin_txid) | ||
| /// is [`ExpectedTxid::Unstable`] it closes the session without checking. | ||
| /// | ||
| /// Deprecated since payjoin 1.3.0: use [`classify`](Monitor::classify) and |
There was a problem hiding this comment.
this is gonna go stale immediatel and should be left out of comments
There was a problem hiding this comment.
I didn't remove the full deprecation comment (since I think that this is the only indicator of deprecation for check_for_transaction in ffi) but just removed the payjoin version.
| /// transaction ID: any ID derived from the proposal before the sender | ||
| /// signs will never appear on the network, and monitoring concludes the | ||
| /// session without checking. | ||
| /// Deprecated since payjoin 1.3.0: use `expected_payjoin_txid` on |
There was a problem hiding this comment.
Again, just removed the version.
DanGould
left a comment
There was a problem hiding this comment.
Thank you for addressing my prior concerns. Your thinking around proposal_txid_is_stable sounds right to me as well.
One thing before merge. Master now wants a payjoin-ffi/CHANGELOG.md line under Unreleased whenever payjoin-ffi/src changes (5db2b57), so this would fail CI rebased on master as-is today even though the rebase is otherwise clean.
The Monitor docs tell the wallet to watch contested_prevouts (mod.rs#L1830-L1834, #L1855-L1863). Most wallets don't need to. The fallback pays the receiver's address, and the proposal spends the receiver's inputs or pays its output, so ordinary wallet sync by script finds both. Your find_settlement doc says the same (v2/mod.rs#L1244-L1248), which contradicts "this is the only way to find the proposal" in the contested_prevouts doc. contested_prevouts is needed when the proposal pays only substituted outputs and spends no receiver input, and to catch a sender spend that is neither transaction. Could the docs lead with passing what the wallet finds to classify, and describe contested_prevouts for those cases? The bindings carry the same text (ffi#L2001-L2006, #L2023-L2032).
Since this needs to be rebased to satisfy the ffi changelog thing, perhaps you could change the deprecation notice to use TBD as well when addressing these nits? This is money. Almost there!
3cbff7b to
d834864
Compare
|
I think CI is failing for this issue: #1985 Otherwise I think ready for re-review. Sorry the rebase commit got lost here, you can find it on my branch https://github.com/xstoicunicornx/rust-payjoin/tree/monitor-revamp-rebase |
There was a problem hiding this comment.
cACK, this is finally looking like the right shape for the Monitor API. I have some code feedback, and I'm not totally sure what to do about the SessionOutcome change. The current approach of always closing with PayjoinProposalSent feels a bit hacky, but I don't want to force a breaking change now.
| pub fn expected_payjoin_txid(&self) -> ExpectedTxid { | ||
| if !self.sender_script_sigs_are_empty() { | ||
| return ExpectedTxid::Unstable; | ||
| } | ||
| // The posted proposal carries the receiver's finalized inputs and no sender signatures, | ||
| // and the sender adds only witnesses, so extracting it yields the broadcast script_sigs. | ||
| let payjoin_tx = | ||
| self.state.psbt_context.payjoin_psbt.clone().extract_tx_unchecked_fee_rate(); | ||
| ExpectedTxid::Stable(payjoin_tx.compute_txid()) | ||
| } | ||
|
|
||
| /// The sender's original transaction, which it may broadcast instead of the proposal. | ||
| pub fn fallback_tx(&self) -> bitcoin::Transaction { self.state.fallback_tx() } |
There was a problem hiding this comment.
I'm not sure we need to make either of these helpers pub, since classify takes care of classification and it's already mentioned that the wallet would automatically detect either a fallback or payjoin tx anyway?
There was a problem hiding this comment.
Yes a wallet can detect a receive, but that doesn't mean the wallet can detect which payjoin session the tx relates to, or that it relates to a payjoin receive at all. Is it acceptable to force wallets to run all received txs through all active Monitor payjoin session's classify method?
| let unsigned_txid = unsigned_tx.compute_txid(); | ||
| let psbt_context = &self.state.psbt_context; | ||
|
|
||
| if unsigned_txid == psbt_context.original_psbt.unsigned_tx.compute_txid() { |
There was a problem hiding this comment.
could we use self.state.fallback_tx.compute_txid()?
There was a problem hiding this comment.
I don't think so because we need to strip the sigs out before comparing the txids to account for non-segwit sender inputs where sender could re-sign same fallback tx (and we probably don't want to classify these as Unrecognized).
|
|
||
| /// Close the session once the wallet no longer needs to track settlement. | ||
| pub fn close(self) -> TerminalTransition<SessionEvent, ()> { | ||
| TerminalTransition::new(SessionEvent::Closed(SessionOutcome::PayjoinProposalSent), ()) |
There was a problem hiding this comment.
I guess this will result in some unused SessionOutcome variants? I also wonder if we might want to rename this one, but am aware that's a breaking change.
close() could take a SettlementOutcome to turn into a SessionOutcome? IDK if that's desirable.
There was a problem hiding this comment.
Actually I think SessionOutcome::Unrecognized(Txid) would be the right shape for closing the session, so that there is a permanent record of the txid that settled it regardless of what it was. But Unrecognized is even more misleading than PayjoinProposalSent and renaming it is a breaking change even if it's never written as of today.
There was a problem hiding this comment.
I think one of the guiding principles for this API change is that we explicitly avoid storing any permanent settlement outcome information. Settlement should strictly be handled by the wallet and we should avoid trying to insert ourselves in that process.
See #1692 (comment) for background on this direction regarding approach.
d834864 to
3612143
Compare
|
Rebasing to resolve merge conflict |
3612143 to
38a4ab1
Compare
|
Ready for re-review. |
2e84523 to
8c1da26
Compare
The staged Dart package takes payjoin-ffi from the pinned revision but payjoin and payjoin-mailroom from crates.io. Staging only switched a crate to the revision when its required version was missing from crates.io. A pull request that changes core without a version bump, which is how core changes normally land, kept the crates.io core, so the reproducible-linux job compiled the pull request's payjoin-ffi against an older payjoin and failed. payjoin#1971 hits this with new Monitor receiver methods. Add a --core-from-revision option that always patches the sibling release crates to the pinned revision and writes the UNPUBLISHED_CORE marker publish.sh refuses, and pass it on pull request runs only. Release runs keep staging against crates.io, so an unpublished core still fails there before anything is published. This also drops the crates.io API probing.
6f369bd to
902166e
Compare
spacebear21
left a comment
There was a problem hiding this comment.
I had my bot review this closely and posted the most relevant findings here
| fn original_psbt(&self) -> &bitcoin::Psbt; | ||
|
|
||
| impl FallbackTx for super::MaybeInputsOwned { | ||
| fn fallback_tx(&self) -> bitcoin::Transaction { | ||
| self.original.psbt.clone().extract_tx_unchecked_fee_rate() | ||
| self.original_psbt().clone().extract_tx_unchecked_fee_rate() | ||
| } | ||
|
|
||
| /// The finalized Payjoin proposal, once the sender may have received it. | ||
| fn payjoin_psbt(&self) -> Option<&bitcoin::Psbt> { None } | ||
| } |
There was a problem hiding this comment.
This extends the sealed trait leak from #1994 with original_psbt and payjoin_psbt now also being unintentionally exposed in the public API. These all build in a downstream crate:
pub fn fallback<S: HasFallbackTx>(r: &Receiver<S>) -> Transaction { r.fallback_tx() }
pub fn original<S: HasFallbackTx>(r: &Receiver<S>) -> Psbt { r.original_psbt().clone() }
pub fn proposal<S: HasFallbackTx>(r: &Receiver<S>) -> Option<Psbt> { r.payjoin_psbt().cloned() }I'm also not sure original is necessary, since it's only used for getting the fallback which is already exposed here.
There was a problem hiding this comment.
Good catch. I pulled the seal commit from #1994 into the base of this branch unchanged, so FallbackTx is pub(crate) here too. It's the same patch, so it drops out when this rebases onto master after #1994 merges. I also added compile_fail doctests for original_psbt and payjoin_psbt next to the one for fallback_tx. They're separate tests because one test with all three calls would still pass if only one leaked.
On original_psbt not being necessary: classify_tx uses it to read the contested prevouts and the original's unsigned txid. Getting those from fallback_tx() would clone and extract the whole PSBT on every call, and the script_sigs would need stripping again. With the trait sealed it's no longer public, so it just stays as an internal accessor.
Drafted with AI assistance.
| // A session that posted its proposal is exempt too, whether still in Monitor or cancelled from | ||
| // it into PendingFallback: it has no protocol work left, the transaction it awaits can confirm | ||
| // long after the mailbox is gone, and a wallet gives up on it by cancelling past expiration. | ||
| if !matches!(receiver, ReceiveSession::Closed(_)) && !history.posted_proposal() { |
There was a problem hiding this comment.
A side effect of this a wallet that relied on the previous behavior to cancel the transaction and broadcast (like the LDK PR does now) would now never know that it needs to cancel and broadcast the transaction. I think the way to address this is to have check_for_transaction keep the old outcome by returning a fatal transition to PendingFallback if the expiration has passed, and only callers that migrate take on the new responsibility.
There was a problem hiding this comment.
I didn't like this option very much because even though it didn't result in an API change it still resulted in a change in how it would need to be handled, which is arguably worse because there is no indicator at compile time that this is the case. So it feels a little dishonest.
I opted to just retain the current deficiency in master which means expired PayjoinProposal and Monitor typestates will error on replay and produce the fallback. I tried many other options to trying to make replaying event log only hit expiration error for the applicable Monitor flows but each had its own slightly messy warts. I think it will be cleaner to add this expiration exclusion with the next major version bump.
Follow up uncovered during this review, FFI's ReceiverReplayError exposes is_expired() but not expiry_fallback_tx(), so binding users can't get the fallback from an expired replay. I'll open a separate PR for it.
| }; | ||
| } | ||
|
|
||
| macro_rules! impl_settlement_classification_for_receiver { |
There was a problem hiding this comment.
I now realize that for FFI, callers would need to write a classify_tx match over all 9 Receiver variants... this is not ideal.
Perhaps classify_tx should live on SessionHistory after all?
There was a problem hiding this comment.
I opted to move this to the general ReceiverSession and have classify_tx return a new Settlement which allows for direct closing of the session. This allows the caller to classify the settlement outcome without consuming the session and gating the closing of the session on the predicate that some settlement outcome was actually reached.
Without the coupled Settlement::close() method, the caller still would need to match on the replayed state to act on the result. Classification becomes uniform, but closing and cancelling don't. The previous match over every variant just moves from classifying to acting. For example if classify_tx was implemented on replay_event_log:
let (session, history) = replay_event_log(&persister)?;
let Some(outcome) = history.classify_tx(&tx) else { return Ok(()) };
if confirmations < MY_BAR { return Ok(()) }
match session {
ReceiveSession::Monitor(r) => r.close().save(&persister)?,
ReceiveSession::MaybeInputsOwned(r) => r.cancel().save(&persister)?.close().save(&persister)?,
ReceiveSession::MaybeInputsSeen(r) => r.cancel().save(&persister)?.close().save(&persister)?,
// ...OutputsUnknown, WantsOutputs, WantsInputs, WantsFeeRange, ProvisionalProposal, PayjoinProposal
ReceiveSession::HasReplyableError(r) => match r.cancel().save(&persister)? {
// MaybeTerminalTransition: PendingFallback if the original arrived, otherwise closed
...
},
ReceiveSession::PendingFallback(r) => r.close().save(&persister)?,
// classify_tx returns None for these, so they can't get here
ReceiveSession::Initialized(_) | ReceiveSession::UncheckedOriginalPayload(_) | ReceiveSession::Closed(_) => {}
}| let unsigned_txid = unsigned_tx.compute_txid(); | ||
|
|
||
| if unsigned_txid == self.state.original_psbt().unsigned_tx.compute_txid() { | ||
| return Some(SettlementOutcome::Fallback); |
There was a problem hiding this comment.
classify_tx returning Fallback before Monitor is new and useful. But nothing tells the wallet what to do next. The answer is cancel(), then close(), with no broadcast because the fallback is already out. The CLI doesn't do it either; its commit says that's left for later.
There was a problem hiding this comment.
With the new API the next step is much clearer - use Settlement::close() to close the session.
| /// | ||
| /// Returns a [`MonitorTransition`] that, once persisted, completes | ||
| /// the session if a transaction is found. | ||
| pub fn check_for_transaction( |
There was a problem hiding this comment.
It seems acceptable to break payjoin-ffi only since it's <1.0.
78dd6a8 to
c48f054
Compare
|
I have not had a chance to fully review the changes but I wanted to push them out incase there was any immediate feedback since there are significant changes (though I do think the changes remove a lot of the inconsistencies and clarify the flow). Will be afk for large part of the day tomorrow but trying to keep this PR moving forward. |
41f23db to
8ce8175
Compare
|
Ok ready for re-review. |
| /// Returns the class of transaction that spent the sender's original inputs. | ||
| pub fn classification(&self) -> ResolutionClass { self.classification } | ||
| } | ||
|
|
There was a problem hiding this comment.
The Resolution struct and classification() are new public API since the last round. AFAICT close(&self, tx: &Transaction) would enforce the same evidence requirement without the wrapper type, the session binding by original txid, or the mismatch error path. Is there a guarantee Resolution gives that I'm missing?
There was a problem hiding this comment.
The only thing it guarantees really is consumption of the receiver session on close() which the previous API didn't.
Other than that, no it doesn't guarantee much more than the previous api. I mostly just didn't like that the previous API was effectuating a state change from something that wasn't actually the receiver session. Felt like a weird anti-pattern. I strongly prefer the receiver session to be the only way to move the state machine and not have a weird proxy object that can indirectly effectuate change on the state machine.
Happy to consider changing it back if you prefer the previous version though.
There was a problem hiding this comment.
I think close(self, tx: &Transaction) would work just as well, it still consumes the session the same way and keeps the receiver as the only thing that moves the state machine, so I think it satisfies both of your points. To be clear, I'm not suggesting going back to the no-argument close().
One concrete reason to prefer taking the transaction: a Resolution carries a classification computed by whichever state produced it, while close decides the outcome from the state that closes. For PayjoinProposal that outcome depends on the stored classification, so a wallet that classified with a stale snapshot (say ProvisionalProposal, which reports the Payjoin as Unrecognized) and then closes the advanced session gets Aborted where a fresh classification would record PayjoinProposalSent. Both states share the original txid, so the session check accepts it. close(self, tx) reclassifies against the closing state, so that can't happen.
Given that, and that Resolution otherwise adds a public struct, an accessor, an FFI object, an original-txid session binding that two sessions with the same original can share, and an extra error path, I'd lean toward classify_tx(&self, tx) -> Option<ResolutionClass> plus close(self, tx: &Transaction) that returns the same transient error when tx spends none of the contested prevouts. And I'd maybe revert the name of the enum to SettlementOutcome, that seems clearer to me.
There was a problem hiding this comment.
Ahh ok sorry I misunderstood. The reason I was leaning against putting the tx as an argument is that it makes close much more fallible. Using Resolution as the argument means that the tx always results in a resolution, whereas that is not the case if you take tx as the argument. This would mean handling the non-classifiable case using a transition with stasis or by wrapping the transition in a Result, both which felt a bit hacky and anti-pattern-ish. I also did not like that intuitively the caller would assume that the tx would be stored as part of the resolution, though this was more of a gut nit.
As for SettlementOutcome I agree its much clearer if it were actually storing the settlement outcome, however what we are storing is essentially just "payjoin was sent and session was closed" or "payjoin was not sent and session was closed". But happy to change this back if you still disagree.
There was a problem hiding this comment.
That's fair, having close take the Resolution means "close with an unrelated transaction" can't even be written, and I agree that's nicer than a runtime error on close.
I think the stale classification issue is actually fixable while keeping this design. It needs an integrator caching bug plus a crash between posting and processing the response, so it's an edge case, but having Resolution hold the actual Transaction and close reclassify it against the closing state would rule it out without changing the API shape.
Not to bikeshed the naming too much but I think I like Resolution, ResolvedBy and resolved_by() as you had it on a previous push. I lean towards keeping it #[non_exhaustive] because it's not going to be persisted anyway, and new variants would likely only refine the catch-all Unrecognized so I don't think forcing a breaking change would be necessary.
There was a problem hiding this comment.
I couldn't quite reason about the flow that would resolve by re-checking classify for a stale classification, as re-classifying would still return the same stale result, but I added in the re-classification anyway as it can't hurt. Could you walk me through the flow that would cause a stale classification?
There was a problem hiding this comment.
The case is when the Resolution and the receiver you call close on are different objects. Re-classifying on the same object would give the same answer, but close now classifies against self, the state that is closing, not the state that minted the resolution. This is what test_close_reclassifies_against_closing_state guards against: the resolution comes from MaybeInputsOwned, which can't recognize the Payjoin and says Unrecognized, and the close happens on PayjoinProposal, which now records PayjoinProposalSent instead of Aborted.
In practice that needs a wallet that keeps an outdated copy of the session around, for example a settlement watcher task that cached the session before it reached PayjoinProposal, while a driver task advances it, posts the proposal, and crashes before persisting PostedPayjoinProposal. The sender then broadcasts the Payjoin, the watcher classifies it with its old copy, and the replayed PayjoinProposal session is closed with that resolution. It needs an integrator bug plus that crash window, so it's an edge case, and only PayjoinProposal cares since Monitor and the earlier states ignore the classification. With the tx carried in the resolution it's now ruled out entirely, which I think is worth the small cost.
8ce8175 to
de6f6ef
Compare
|
approach ACK My bot found a few messaging discrepancies I'll re-post here but none seem blocking:
|
fef5691 to
26c8315
Compare
After posting the proposal the receiver still does not know how the sender's inputs were spent. The proposal and the fallback double-spend them, so the receiver holds the only record that can tell which transaction represents which. Expose that as a pure classify_tx over a transaction the wallet found. Wallets should pass every transaction they receive to classify_tx on each open session, rather than probing for predicted txids. A session in any state with a fallback can see the fallback or a re-spend of the sender's inputs, not only one in Monitor. A transaction unrelated to a session is rejected by an outpoint comparison before any hashing, so checking it against every session is cheap. So classify_tx lives on every HasFallbackTx state. The sealed FallbackTx trait now returns a borrowed original PSBT, with fallback_tx derived from it as a default method, and a payjoin_psbt that defaults to None. PayjoinProposal and Monitor return their finalized proposal. PayjoinProposal counts because a post can reach the sender even when persisting the transition out of that state fails. ProvisionalProposal returns None: its unsigned transaction matches what finalization produces, but the sender cannot have it yet. Before PayjoinProposal, classify_tx never reports Payjoin. The trait is pub(crate), so generic code bounded on HasFallbackTx cannot call original_psbt or payjoin_psbt from outside the crate any more than fallback_tx. Add a compile_fail doctest for each next to the one guarding fallback_tx. Each needs its own, since one test with several calls would pass while any one of them still failed to compile. classify_tx answers which of this session's transactions spent the contested prevouts. It returns a Resolution whose ResolvedBy is Payjoin for the proposal, Fallback for the fallback, and Unrecognized for any other transaction that spends a contested prevout. A transaction spending none of them says nothing about the session, so it gets None rather than Unrecognized. The Resolution exposes no txid, since the caller passed in the transaction and already has it. Identity compares the transaction's txid, with its script_sigs cleared, against each PSBT's unsigned transaction. Signing fills only script_sig and witness, and the txid already excludes the witness, so for a stable session this is the plain txid check. It also recognizes the proposal after a non-SegWit sender's signature changed its txid, and the fallback after a third party malleated it. Matching on the receiver's inputs or the proposal's output set would also accept a different transaction that happens to share them. A reordered output set is a different transaction no receiver signature covers. The fallback is checked first. The two only coincide when the proposal is the original unchanged, and then no cooperation happened. Because every candidate spends the contested prevouts, one transaction is the whole answer, and choosing which to ask about is the wallet's job. Keep the contested prevouts private. A wallet that classifies every transaction it receives does not need to watch them: sync by script finds the fallback, which pays the receiver, and the proposal, which spends the receiver's inputs or pays its outputs. The one proposal sync misses pays only scripts the wallet does not own, as when it forwards the payment to a third party. The wallet chose those scripts itself, so it is the wallet's job to watch them. Document that on substitute_receiver_script. A wallet that classifies what it receives has no use for a predicted txid, the fallback, or the receiver's prevouts, and SessionHistory::fallback_tx already returns the fallback for a caller that wants it. It does need a deadline: nothing else ends a session the sender never settles, or settles with a re-spend the wallet never sees. The session's expiration stays that deadline. Past it, replay returns the expired error carrying the fallback, as for any open session, and a wallet can broadcast it from there. payjoin-cli prints it for a manual broadcast. Document it on Monitor and pin it with a test. check_for_transaction still probes by txid, so compute the proposal's txid privately from the posted proposal. Its txid then includes the script_sigs of the receiver's finalized inputs. The proposal carries no sender signatures, and a SegWit sender adds only witnesses, so this is the txid the broadcast transaction has. Hashing the unsigned proposal instead misses a legacy or P2SH-wrapped receiver input and predicts a txid that never appears on chain. proposal_txid_is_stable checks only the sender's inputs, so it has the same flaw. Before the receiver signs there is no script_sig to read, and fixing it there would mean inferring from script types. Deprecate it in favor of classify_tx, which recognizes the proposal whatever its txid, and narrow its doc to what it checks. Add close to the same states. It takes the Resolution and ends the session once the wallet's confirmation bar is met. Resolution has private fields and no constructor, so only classify_tx makes one, and a session can close this way only after a transaction spent its contested prevouts. Then no fallback needs broadcasting: the fallback is that transaction or conflicts with it. Closing without that evidence would let a wallet end a session holding a fallback it never saw, so every other way out still goes through cancel, which hands the fallback over. Resolution is not Serialize, so it cannot be forged by deserializing. close lives on the receiver, as every other transition does, so only receivers write session events and a Resolution is only evidence handed back to one. It records the original transaction's txid, and close rejects a Resolution classified from another session the way the input checklists reject items marked for a different receiver: with a transient error that returns the receiver and persists nothing. The Resolution also carries the transaction, and close classifies it again against the state it closes from, not the one that classified. A stale copy of the session from before the proposal calls the Payjoin Unrecognized, and closing PayjoinProposal with that verdict would record Aborted although the proposal reached the sender. ResolvedBy is never persisted: only confirmation resolves a double-spend race and a reorg can always reverse it, while the log is append-only and Closed is terminal, so a verdict written there would be permanent and could later be wrong. Closing records what the protocol did. A Monitor session closes as PayjoinProposalSent whichever transaction resolved it. A PayjoinProposal session resolved by its Payjoin closes the same way: the sender signing the proposal proves the post reached it, and a reorg cannot undo that. Any other resolution before the handoff closes as Aborted. Keeping the session open until the wallet closes it also makes the log the record of which sessions still owe an answer, which a wallet-side cache cannot replace because a restored backup brings the logs back without it. A wallet that gives up on a session nothing resolved cancels it and broadcasts the fallback. Add ReceiveSession::classify_tx and ReceiveSession::close, which dispatch to the state's receiver. classify_tx returns None for the states that do not support classification, and close rejects a Resolution in those states, since none of them can have produced it. A wallet that replays its open sessions then classifies and closes without matching on every state. Re-express check_for_transaction over the classifier so a found transaction is confirmed as the proposal rather than trusted from the txid probe alone, and route its non-SegWit exit through the private txid helper. Deprecate it in favor of classify_tx and close. It closes on first sight rather than at a confirmation bar, never sees a spend that is neither transaction, and closes an unstable session without checking at all. The binding and the CLI still call the deprecated methods, so allow the deprecation at those call sites. Both deprecations use since = "0.0.0-unreleased", a placeholder the release replaces with the real version rather than this commit guessing it. The existing Monitor tests keep covering check_for_transaction, its early exit for non-SegWit senders included, under allow(deprecated). New regression tests cover its probe of a txid with a receiver script_sig, and proposal_txid_is_stable, until both are removed. The new tests classify each kind of spend and close with the Resolution from MaybeInputsOwned, PayjoinProposal and Monitor, checking the outcome each writes, check that close classifies again against the state it closes from, and check that close rejects a Resolution from another session, including one whose transaction spends this session's inputs, or in a state without a fallback.
Every terminal outcome reads as a payment verdict today. Aborted says the payjoin "was not successful" when a fallback may well have been broadcast and confirmed, and PayjoinProposalSent still describes non-SegWit senders as unmonitorable, which classify_tx now makes untrue. Say what each outcome means for the protocol. Aborted is a session that ended without acknowledgement that the directory received its proposal, or was cancelled, and the fallback may still have paid. That can happen after the proposal was posted, since Monitor can still cancel into PendingFallback and close from there. PayjoinProposalSent is a session whose proposal was sent. Note on Success and FallbackBroadcasted that only the deprecated check_for_transaction produces them, so sessions closed with classify_tx and close never carry them. SessionStatus matters more, since wallet UIs read status(). Document every variant in one line. Completed is a session that closed after its proposal was sent, without saying which transaction resolved it, and FallbackBroadcasted, like its SessionOutcome, comes only from the deprecated check_for_transaction. Record on Unrecognized that nothing produces it. The variant was reserved for a classifier that would have persisted its verdict. It stays because the enum is exhaustive, so removing it is a semver break.
The receiver gained a classifier on every state with a fallback, and a close that takes its Resolution, but bindings could still only call check_for_transaction, which probes two predicted txids and closes on the first match. Wallets built on the bindings had no way to apply their own confirmation bar or to recognize a Payjoin whose txid a non-SegWit sender changed. Expose classify_tx and close_session on every state from MaybeInputsOwned through Monitor, the same states that cancel into PendingFallback, through one macro like the cancel methods. Wallets are meant to classify every received transaction against each open session, so the binding needs both wherever core has them. Expose Resolution as an object with resolved_by, ResolvedBy as a uniffi enum, and a CloseTransition to persist the close. A uniffi object has no constructor unless one is exported, so foreign code cannot make a Resolution either, which keeps the guard that core's private fields give Rust callers. Name the method close_session rather than close. Kotlin objects are AutoCloseable, whose close() drops the Rust handle, so a close on nine state objects would need nine renames in uniffi.toml and would leave close() and closeSession() side by side on each. Expose ReceiveSession::classify_tx and ReceiveSession::close as the top-level functions classify_receiver_tx and close_receiver_session rather than as methods on the ReceiveSession enum. uniffi-dart 0.2.1 renders methods only on objects, so an enum method would be missing from the Dart bindings, and uniffi-bindgen-react-native would render it as a static function taking the enum anyway. Both convert the binding's session back to core's and dispatch there. classify_receiver_tx decodes the transaction in every state, so bad bytes fail the same way whatever the session's state. A Resolution from another session, or a state that cannot be closed via resolution, fails CloseTransition.save with the transient ReceiverPersistedError that saving already returns. Carry core's note on watching forwarded outputs over to substitute_receiver_script. classify_tx takes consensus-encoded bytes like the rest of the binding, so it returns a TransactionParseError when they do not decode. The core ResolvedBy is non_exhaustive; a value this binding does not know maps to Unrecognized rather than panicking. Remove check_for_transaction, with the TransactionFinder callback and MonitorTransition it needed, and proposal_txid_is_stable from every receiver state, rather than deprecating them as core does. payjoin-ffi is not yet 1.0, so it can drop them now, and uniffi cannot carry note binding users may never see. Record the additions and removals under Unreleased in the FFI changelog, as the changelog check requires for a change to payjoin-ffi/src. Exercise the new API in every binding's tests. The v2 integration test saves the receiver's Monitor, classifies the broadcast Payjoin with Monitor.classify_tx and with classify_receiver_tx on the replayed session, and closes the replayed session with close_receiver_session. A unit test checks that classify_receiver_tx returns nothing for a session without a fallback and rejects bytes that are not a transaction.
After posting its proposal the receiver polled the mempool for a predicted txid for a few seconds and closed on first sight. It closed sessions with non-SegWit senders without checking at all. Have resume check the wallet once for each open receiver session, in any state, before driving it. Every wallet transaction paying the session's address is classified against the session. The CLI never substitutes the receiver output, so both the fallback and the Payjoin pay that address. Once the most-confirmed transaction spending the sender's inputs has one confirmation, close the session with its Resolution. With fewer, leave the session open without advancing its protocol. Otherwise drive the session as before; it stops at Monitor until a later resume finds a transaction that resolves it. bitcoind-async-client has no wrapper for listreceivedbyaddress, so enable its raw_rpc feature and call it directly. Stop printing the proposal txid for the user to watch. It was the unsigned proposal's, which is wrong for non-SegWit senders.
cancel saves the Cancelled event before it broadcasts the fallback, so a failed broadcast leaves the session in PendingFallback. That happens when the Payjoin or the fallback is already on chain. Every later resume then repeats the hint to run cancel, and cancel fails the same way each time. cancel --no-broadcast closes the session from that state, but nothing told the user about it. Say the session is still open when the broadcast fails and point to cancel --no-broadcast. Mention the flag in the PendingFallback hint too, which a session reaches after handle_error prints the fallback for a manual broadcast. Sender and receiver share the same cancel flow, so change both.
26c8315 to
71f0a1b
Compare
|
Ok ready for re-review. |
spacebear21
left a comment
There was a problem hiding this comment.
utACK 71f0a1b - I mostly focused my review on the API design which I think is the right shape now. I didn't look at payjoin-cli very closely but it seems sane at a glance and the new e2e test is a good addition.
Some follow-ups to consider but non-blocking for this PR:
- Expose
contested_prevouts: this would be useful for wallets to build an index of their sessions. IIRC we had decided to ship this step improvement and see what API demands come up, before committing to a new public interface. - A classifier on
SessionHistorythat also works for closed and canceled sessions. Same as above, I'm not convinced it's a strict requirement for the next release. closedocstring should say closing from Monitor records PayjoinProposalSent whichever transaction resolved it, and that the classification isn't persisted.cancel --no-broadcaststill prints "Broadcast the original transaction manually", which contradicts the new hint pointing there when the fallback is already on chain. Maybe "Session closed without broadcasting the fallback. If it isn't already on chain and its inputs are unspent, broadcast it yourself:".- FFI migration notes:
- close_session records PayjoinProposalSent for every resolution, where check_for_transaction recorded Success(txid) or FallbackBroadcasted, so apps should store resolved_by and the txid themselves.
- classify_tx resolves unconfirmed transactions too, so close only after the wallet's confirmation depth.
- Non-SegWit senders no longer need special handling.
- Resolution can't be persisted, so reclassify after a restart.
- Bad bytes raise TransactionParseError.
Supersedes #1692 .
After posting a proposal, the receiver has to find out whether the Payjoin, the fallback, or some other transaction spent the sender's inputs. Today
check_for_transactionhandles this by probing two predicted txids and closing the session on the first match. It writes a verdict a reorg can reverse, it never sees an unrelated spend, and it closes non-SegWit sessions without checking at all.This PR gives the wallet what it needs to answer the question, and lets the wallet decide when the answer is final.
Much of the design iteration and rationale for this implementation lives in #1692.
Changes
Core
receive::v2::Receiverstate that holds a fallback transaction and is advancing the Payjoin protocol, fromMaybeInputsOwnedthroughMonitor, gains:classify_tx(tx), which returns aResolutionfor a transaction spending any of the sender's original inputs, orNoneif it spends none of them.Resolution::resolved_by()returns aResolvedByofPayjoin,FallbackorUnrecognized. The match ignoresscript_sig, so a non-SegWit signature or third-party malleation doesn't hide the proposal or the fallback. Any other change, such as a fee bump, reordered outputs or a sender double-spend, isUnrecognized. States beforePayjoinProposalnever reportPayjoin.close(resolution), which ends the session once the wallet decides the transaction has enough confirmations. It classifies the resolution's transaction again against the closing state, so a resolution from a stale copy of the session can't record a stale outcome. It recordsPayjoinProposalSentfromMonitor, and fromPayjoinProposalwhen the Payjoin resolved it, andAbortedotherwise. No settlement verdict is ever persisted.ReceiveSession::classify_txandReceiveSession::closedo the same for a session in any state, so a wallet replaying its open sessions doesn't have to match on every state. States that don't support classification returnNone, and closing them fails.closerejects aResolutionclassified against a different original transaction with a transient error that returns the session and persists nothing. Onlyclassify_txmakes aResolution.check_for_transactionis deprecated in favor ofclassify_txandclose, and now goes through the classifier.proposal_txid_is_stableis deprecated too, since it checks only the sender's inputs. Both use a placeholdersinceuntil the release version is set.SessionOutcomeandSessionStatusdocs now describe what the protocol did, not how the payment settled.FFI
classify_txandclose_sessionon each of those states, plusclassify_receiver_txandclose_receiver_sessionfor aReceiveSessionin any state. Transactions are passed consensus-encoded, and bytes that don't decode returnTransactionParseError.Resolutionobject, theResolvedByenum andCloseTransition.Monitor.check_for_transaction, with itsTransactionFindercallback andMonitorTransition, and removesproposal_txid_is_stable.CLI
resumelooks in its wallet for transactions paying the receiver's address, classifies them against every open receiver session in any state, and closes a session once its resolving transaction has one confirmation. Before, it closed on the first mempool sighting. An unresolved session stays open across resumes, and sessions with non-SegWit senders are now tracked too.cancelfails to broadcast the fallback, it says the session is still open and points tocancel --no-broadcastto close it.Assigning to @spacebear21 for review.
Disclosure: This description and the code changes were written with Claude Code.
Pull Request Checklist
Please confirm the following before requesting review: