A Stellar claimable balance is easy to misread because it bundles three events that a wallet user tends to treat as one. CAP-0023, the protocol proposal that defines it, introduces a new ledger entry type and two operations whose entire purpose is to split sending from receiving. That separation is useful, because it lets an account initiate a payment to a destination that is not yet prepared to accept the asset, but it also means the evidence that an entry was created, that an account became eligible to claim it, and that the asset actually arrived are three different records. This guide walks through what each stage does and does not prove, strictly against the CAP-0023 text.
Three separate events
CAP-0023’s central design statement is that a payment can be divided into creation and receipt. A creation record answers one narrow question: did an operation establish a claimable entry under the documented rules? A claimant record identifies an account that could potentially claim that entry. A successful claim is the later transition that credits the specified asset and consumes the entry. Treating all three as payment received erases the very distinction the proposal exists to make. When something appears missing, the useful first question is not whether the payment was made, but which of these three events has supporting evidence.
Keep the account roles separate
The entry itself carries identifiers worth keeping distinct: the balanceID, the specified asset, its amount, and its claimants. Copy the balanceID from the record rather than trying to reconstruct it. Three account roles matter. The creating operation’s source is the account whose funding and other checks are tested. The transaction source is stored as createdBy, which the document says is the source of the transaction, not the operation. The claim operation’s source is the account checked against a claimant destination and, on success, credited with the asset. Collapsing these into one creator hides a real routing detail: under the documented rules, createdBy plays a specific role in the reserve-return branch even when a different account supplied the creating operation.
Creation funding is not receiving readiness
Creating an entry is not the same as being ready to receive. Creation checks native-asset reserve requirements separately from asset funding, and it requires the operation source to hold a trustline for the asset with the authorized flag set. An account that can fund the asset amount might still fail the reserve check, and an account with the right relationship might still fail authorization. One asymmetry is worth preserving rather than repairing: the creation prose does not state a native-asset exception to its trustline checks, while the claim prose explicitly limits its trustline and authorization checks to non-native assets.
The claim checks run in order
The claim operation tests conditions in sequence. If no entry matches the balanceID, the result is a does-not-exist code. If the claim source is not a listed claimant or its predicate is not satisfied, the result is a cannot-claim code. Only then does reserve routing run: the reserve returns to createdBy if that account exists and has native capacity, otherwise the claim source becomes the fallback. For non-native assets, trustline and authorization checks then produce no-trust or not-authorized results, and insufficient capacity produces a line-full result. A line-full result is ambiguous on its own, because the same label appears for the native-reserve fallback and for the claimed asset. Naming which value and which account is being examined is the difference between a useful diagnostic and a guess.
Predicates are conditions, not proof of receipt
A predicate is a condition on a claimant’s ability to claim: unconditional, combinations such as AND, OR and NOT, or time-based before absolute or relative time. A satisfied predicate answers a permission question; it does not prove that a claim operation succeeded. Relative time is anchored to the ledger close time at creation and converted into an absolute predicate, so it is not a countdown that begins when someone first notices the payment.
What to record
A useful read-only record names the entry and its asset, distinguishes the creating operation source from createdBy, and states the proposed claim source. It then separates claimant matching, predicate evaluation, reserve routing, trustline authorization, and asset capacity, marking what is observed against what is assumed. Until a successful claim record exists, keep entry created, claimant eligible, and asset received as three separate findings.
Source: BTC-Pulse.