A Stellar claimable balance, as described in CAP-0023, separates three events that a wallet user might otherwise treat as one: creating a ledger entry, meeting the conditions to claim it, and successfully receiving its asset. Evidence of the first event does not establish the other two. An eligible account can still encounter a receiving check that prevents a successful claim.
This guide explains the reviewed CAP-0023 document, not verified current deployment. Its preamble names Jonathan Jove as author, marks the proposal Final, and records creation on June 4, 2019, an update on February 5, 2020, and protocol version 14. Those are document facts, not an activation date or proof of present implementation. The document also points to a later XDR update that is outside this guide’s evidence.
1. Establish what the payment record actually proves
The central design statement in CAP-0023’s payment summary is that the proposed operations separate sending a payment from receiving it. The motivation is to let an account initiate payment when the destination is not necessarily prepared to receive the asset. The resulting separation is useful, but it changes what counts as evidence of completion.
A creation record answers whether the operation established a claimable entry under the documented rules. A claimant record identifies an account that could potentially claim that entry. A successful claim establishes the later transition that credits the specified asset and consumes the entry. Treating all three as “payment received” would erase the very distinction the proposal introduces.
For a missing-payment investigation, begin with a narrower question: which event has supporting evidence? A sender’s description of an intended payment is not an entry record. An entry record is not receiving-account credit. This is a diagnostic framework, not a diagnosis of any real account; no transaction or account history was supplied for this guide.
2. Identify the entry and keep the account roles separate
CAP-0023 describes each ClaimableBalanceEntry as an independent entity on the ledger. A useful read-only record therefore starts with the entry’s balanceID, specified asset, amount and claimants. Copy the identifier from the relevant record rather than trying to reconstruct it from an incomplete extract of the technical schema.
Next, distinguish three account roles. The creating operation’s source is the account used for its funding and other creation checks. The transaction source is stored as createdBy; the document expressly says this is the source of the transaction, not the operation. The later claim operation’s source is the account tested against a claimant destination and, on success, credited with the claimed asset. These roles should not be collapsed into an ambiguous “creator” field.
The broader distinction between ledger representation versus displayed balance helps explain why an entry and a wallet total answer different questions. That comparison does not make a Stellar claimable balance a Bitcoin UTXO or import Ethereum’s account rules. Here, the relevant fact is simply that CAP-0023 describes a separate ledger object whose existence does not itself establish credit to the intended receiving account.
This role separation becomes especially important during reserve routing. A report that identifies only who funded the creating operation can omit the transaction source stored in createdBy. Under the reviewed rules, that stored account has a specific role in the later reserve-return branch, even when another account supplied the creating operation’s source.
3. Separate creation funding from receiving readiness
The creation semantics in CAP-0023 distinguish native-asset reserve requirements from funding of the specified asset. They list a low-reserve failure, trustline and authorization failures, and an underfunded failure. An account’s ability to fund the asset amount therefore does not, by itself, answer whether it satisfies the separate reserve requirement.
A trustline is the asset-specific account relationship referenced by the document’s holding and authorization checks. In the creation prose, the operation source must have a trustline for the asset and the trustline must carry AUTHORIZED_FLAG. The same section separately checks available asset funding. These are distinct questions: whether the account has the required relationship, whether it is authorized, and whether it has enough available value.
There is an important documentary limit. The creation prose does not state a native-asset exception to its trustline checks, whereas the later claim prose explicitly limits its trustline and authorization checks to non-native assets. This guide preserves that asymmetry rather than silently repairing the text or presenting it as a complete native-asset creation algorithm. Current reserve values and later implementation rules require additional documentation.
Creation also has malformed-input conditions. The listed examples include an invalid asset, a nonpositive amount, an empty claimant list, duplicate claimant destinations and certain predicate defects. These validation conditions are different from insufficient funding. Finally, the document lists debit and failure steps; their order is not evidence that earlier debits persist independently when a later step fails. General transaction rollback behavior is outside the reviewed record.
4. Test entitlement to the account, not just possession of a key
The claimant-account design rationale describes a finite, immutable list of accounts that could potentially claim an entry. “Potentially” matters. Being listed establishes one part of the entitlement test, not an unconditional right to receive the asset at any time or into any destination.
The design deliberately binds the claim to an account rather than allowing a listed key to redirect the asset freely into another account. CAP-0023 explains that making entries claimable into arbitrary accounts would weaken asset authorization restrictions. Its rationale also acknowledges a conditional stranded-entry risk: satisfiable conditions do not guarantee that an entry will remain practically claimable.
The distinction between signing authority and recovery material is useful here. Restoring a backup may restore the ability to authorize actions, but it does not rewrite this proposal’s claimant destinations or waive asset authorization checks. That linked guide explains the general difference between credentials and recovery scope; it is not a Stellar account-recovery procedure.
For a read-only investigation, record the proposed claim operation’s source account and compare it with the listed claimant destination. Do not substitute “the user controls a key” for that account comparison. Public records can be examined without disclosing private keys or recovery phrases, and this framework requires no demonstration signature or secret-sharing exercise.
5. Interpret predicates as conditions, not proof of payment
A predicate is a condition attached to a claimant’s ability to claim. The reviewed schema names unconditional, AND, OR, NOT, before-absolute-time and before-relative-time categories. Conceptually, these allow an unconditional permission, combinations of conditions, negation and time-related restrictions. A satisfied predicate answers a permission question; it does not establish that a claim operation succeeded.
CAP-0023’s relative-time conversion rule anchors a relative before-time condition to ledger data. During creation, the relative value is added to closeTime in the LedgerHeader and converted into an absolute-time predicate. If that addition exceeds INT64_MAX, the document specifies using INT64_MAX.
The diagnostic consequence is that a relative condition is not a countdown beginning whenever a reader opens a wallet or notices the payment. Its documented anchor is the ledger close time used during creation. An investigation needs the relevant stored condition and ledger context, not an estimate based on when someone first saw a notification.
The supplied technical extraction contains incomplete XDR comparisons. This guide therefore does not reconstruct missing operators or state what happens at exact deadline equality. It also avoids inventing a timestamp for an example. Where a boundary decision matters, mark it unresolved until intact, relevant versioned documentation establishes the rule. More precision than the evidence supports would make the diagnosis less reliable, not more useful.
6. Follow the claim checks before assuming reserve return
The claim-operation semantics first test whether an entry matching balanceID exists. If none exists, the listed result is CLAIM_CLAIMABLE_BALANCE_DOES_NOT_EXIST. The next test compares the claim operation’s source with a claimant destination and requires that claimant’s predicate to be satisfied. Failure there produces CLAIM_CLAIMABLE_BALANCE_CANNOT_CLAIM.
Only after those tests does the documented sequence address reserve routing. It first considers createdBy. If that account exists and has sufficient available native-asset capacity for the reserve, the listed route adds the reserve there. If the account does not exist or lacks that capacity, the sequence instead checks the claim operation’s source as the fallback recipient of the native reserve.
That fallback can fail with CLAIM_CLAIMABLE_BALANCE_LINE_FULL when the claim source lacks sufficient available native-asset capacity. This is a reserve-capacity failure, not necessarily a problem with the specified asset’s trustline. Later in the sequence, the same result label appears for insufficient capacity to receive the claimed asset. The code alone therefore cannot identify the relevant branch.
The account stored in createdBy is consequently relevant even when it is not the claimant receiving the asset. Conversely, receiving a reserve under the described route is not the same event as recovering the claimable asset. These are separate values with separate routing rules. The sequence should also not be read as proof that an intermediate reserve credit remains after a later failed check; the reviewed body does not establish that broader execution behavior.
7. Apply a qualitative control-and-state matrix
Consider a conceptual hypothetical, not a real payment. Assume successful creation of a non-native-asset entry, distinct sender and recipient accounts, and continued entry existence at every pre-claim observation. For simplicity, the sender is both the creating operation source and transaction source. Both accounts are explicitly listed as claimants: the recipient has a before-time predicate, and the sender has its negation. No exact time-boundary rule is assumed.
| Observed state | What it establishes | What remains unproved |
|---|---|---|
| Recipient predicate is satisfied, but its required trustline is absent. | The recipient meets the assumed account-and-predicate test. | A successful claim and asset receipt; the receiving check still blocks success. |
| Sender predicate is later satisfied and the entry still exists. | The explicitly listed sender may attempt a claim. | Success through reserve routing and applicable receiving checks. |
| createdBy is unavailable or lacks native-reserve capacity. | The documented fallback checks the claim source. | Sufficient native capacity there; LINE_FULL remains possible. |
| A claim succeeds. | The claim source receives the asset and the entry is deleted. | Any separate payment beyond that entry or any unrelated account credit. |
Scroll the table horizontally to see all columns.
The analytical point is that permission can change while receipt remains unestablished. A recipient can satisfy its condition yet lack a required trustline. A sender can later satisfy its own condition yet still fail a receiving check. Neither observation is equivalent to an automatic transfer.
The sender’s potential route in this example comes from its explicit claimant entry and satisfied predicate, not from having funded creation or being stored as createdBy. Without that listed entitlement, the same recovery inference would be unsupported. The table is a reasoning aid, not an instruction to construct, sign or broadcast such an arrangement.
8. Distinguish asset receipt from reserve routing and entry consumption
After reserve routing, CAP-0023 expressly applies its receiving trustline and authorization checks when the specified asset is not native. An absent trustline produces CLAIM_CLAIMABLE_BALANCE_NO_TRUST; a trustline without the required authorization flag produces CLAIM_CLAIMABLE_BALANCE_NOT_AUTHORIZED. Those native-asset exceptions are explicit here, unlike the creation-side wording discussed earlier.
The next check asks whether the claim source has sufficient available capacity for the asset amount. Insufficient capacity produces CLAIM_CLAIMABLE_BALANCE_LINE_FULL. This is the claimed-asset branch, distinct from the native-reserve fallback branch. A useful diagnostic report names which value and receiving account are being examined instead of translating every LINE_FULL result into “the asset trustline is full.”
The successful-claim sequence then adds the specified asset amount to the claim source, deletes the entry and reports success. In the hypothetical, that consumption means the other claimant cannot subsequently obtain a duplicate claimable amount from the same entry. Merely becoming eligible does not consume it; the documented successful claim does.
The distinction between asset identity versus recipient acceptance offers a limited parallel: knowing what asset a record names does not establish that the destination can receive and use it. CAP-0023 is not a cross-chain route or bridge tutorial. Its relevant receiving conditions are the account, predicate, reserve and asset checks described in this document.
Nor does the reviewed mechanism describe an automatic timeout refund. A change in a time predicate can make a listed claimant eligible, but the document says an entry can only be deleted by the claim operation. Returning the native reserve to createdBy is also not an automatic return of the claimable asset. Any sender-recovery conclusion needs evidence of claimant entitlement and a successful claim.
9. Finish with a bounded diagnostic record
A completed read-only record should identify the entry and specified asset, distinguish the creating operation source from the transaction source stored as createdBy, and name the proposed claim source. It should then separate claimant matching, predicate evaluation, reserve routing, non-native trustline authorization and asset capacity. For each field, distinguish observed public evidence from an assumption or an unresolved question.
If a check reports DOES_NOT_EXIST, record only what that check establishes: no matching entry was found under the described rule. That result alone does not prove prior creation, identify a successful claimant or establish a refund. Resolving the history requires additional creation or claim records. Likewise, a transaction memo should not replace entry identity: CAP-0023 explicitly treats memo as a property of a transaction, not an operation or ledger entry.
The useful endpoint is a precise unresolved question, such as whether a named claim source satisfied the receiving check in a documented attempt. Until a successful claim record establishes receipt, keep “entry created,” “claimant eligible” and “asset received” as three separate findings.
