Skip to main content

Claimable Balances

Claimable balances were introduced in CAP-0023 and are used to split a payment into two parts:

  1. Sending account creates a payment, or ClaimableBalanceEntry, using the Create Claimable Balance operation.
  2. Destination account(s), or claimant(s), accepts the ClaimableBalanceEntry using the Claim Claimable Balance operation.

Claimable balances allow an account to send a payment to another account that is not necessarily prepared to receive the payment. They can be used when you send a non-native asset to an account that has not yet established a trustline, which is useful for anchors onboarding new users. A trustline must be established by the claimant to the asset before it can claim the claimable balance; otherwise, the claim will result in an op_no_trust error.

Claimant Permanence

Unclaimed claimable balances sit on the ledger forever, taking up space and ultimately making the network less efficient. Thus, it is best practice to put one of your own accounts as a claimant (assuming no issuer clawbacks). Then you can accept your own claimable balance if needed, freeing up space and [account reserves].

Each ClaimableBalanceEntry is a ledger entry, and each claimant in that entry increases the source account’s minimum balance by one base reserve.

Once a ClaimableBalanceEntry has been claimed, it is deleted.

Operations​

Create Claimable Balance​

For basic parameters, see the Create Claimable Balance entry in our List of Operations section. (/_ ⚠ Should probably be together _/)

Other Parameters​

  • Claim_Predicate_ Claimant: An object that holds both the destination account that can claim the ClaimableBalanceEntry and a ClaimPredicate that must evaluate to true for the claim to succeed.

  • ClaimPredicate: A recursive data structure that can be used to construct complex conditionals using different ClaimPredicateTypes. Below are some examples with the Claim_Predicate_ prefix removed for readability. Note that the SDKs expect the Unix timestamps to be expressed in seconds.

    • UNCONDITIONAL: Can claim at any time.
    • BEFORE_RELATIVE_TIME(X): Can claim if the close time of the ledger including the claim is before X seconds, plus the ledger close time in which the ClaimableBalanceEntry was created.
      • NOT( BEFORE_RELATIVE_TIME(X) ): Can claim if the close time of the ledger including the claim is at or after X seconds, plus the ledger close time in which the ClaimableBalanceEntry was created.
    • BEFORE_ABSOLUTE_TIME(X): Can claim if the close time of the ledger including the claim is before X (Unix timestamp).
      • NOT( BEFORE_ABSOLUTE_TIME(X) ): Can claim if the close time of the ledger including the claim is at or after X (Unix timestamp).
    • AND[ NOT( BEFORE_ABSOLUTE_TIME(X) ), BEFORE_ABSOLUTE_TIME(Y) ]: Can claim between X and Y Unix timestamps (given X < Y).
    • OR[ BEFORE_ABSOLUTE_TIME(X), NOT( BEFORE_ABSOLUTE_TIME(Y) ) ]: Can claim outside X and Y Unix timestamps (given X < Y).

  • ClaimableBalanceID: ClaimableBalanceID is a union with one possible type (CLAIMABLE_BALANCE_ID_TYPE_V0). It contains an SHA-256 hash of the OperationID for claimable balances.

  • ClientBalanceID: Hex of ClaimableBalanceID returned after a successful CreateClaimableBalance operation. The ClaimClaimableBalance operation uses this (with zero-padding to 72 characters) to claim the ClaimableBalanceEntry.

Claim Claimable Balance​

For basic parameters, see the Claim Claimable Balance entry in our List of Operations section.

This operation will load the ClaimableBalanceEntry that corresponds to the ClientBalanceID and then search for the source account of this operation in the list of claimants on the entry. If a match on the claimant is found, and the ClaimPredicate evaluates to true, then the ClaimableBalanceEntry can be claimed. The balance on the entry will be moved to the source account if there are no limit or trustline issues (for non-native assets), meaning the claimant must establish a trustline to the asset before claiming it.

Clawback Claimable Balance​

This operation claws back a claimable balance, returning the asset to the issuer account, burning it. You must claw back the entire claimable balance, not just part of it. Once a claimable balance has been claimed, use the regular clawback operation to claw it back.

You clawback a claimable balances with its ClientBalanceID.

Learn more about clawbacks in our Clawback Guide.

Example​

The below code demonstrates how an account (Account A\mathcal{A}) creates a ClaimableBalanceEntry with two claimants: A\mathcal{A} (itself) and Account B\mathcal{B} (another recipient).

Setup​

Each of these accounts can only claim the balance under unique conditions. B\mathcal{B} has a full minute to claim the balance before A\mathcal{A} can reclaim the balance back for itself.

The reclaim logic acts as a safety net if none of the predicates can be fulfilled.

Go Helper Functions
func fundAccount(rpcClient *client.Client, address string) error {
  ctx := context.Background()

  // Use GetNetwork method from client
  networkResp, err := rpcClient.GetNetwork(ctx)
  if err != nil {
    return err
  }

  if networkResp.FriendbotURL != "" {
    friendbotURL := networkResp.FriendbotURL + "?addr=" + url.QueryEscape(address)
    resp, err := http.Post(friendbotURL, "application/x-www-form-urlencoded", nil)
    if err != nil {
      return err
    }
    defer resp.Body.Close()

    if resp.StatusCode != 200 {
      return fmt.Errorf("friendbot failed with status: %d", resp.StatusCode)
    }
    return nil
  }

  return fmt.Errorf("friendbot not configured for network - %s", networkResp.Passphrase)
}

func panicIf(err error) {
  if err != nil {
    log.Fatal(err)
  }
}
import time
from stellar_sdk.xdr import TransactionResult, OperationType
from stellar_sdk.exceptions import NotFoundError, BadResponseError, BadRequestError
from stellar_sdk import (
    Keypair,
    Network,
    Server,
    TransactionBuilder,
    Transaction,
    Asset,
    Operation,
    Claimant,
    ClaimPredicate,
    CreateClaimableBalance,
    ClaimClaimableBalance
)

	var txResult xdr.TransactionResult
	err := xdr.SafeUnmarshalBase64(resp.ResultXDR, &txResult)
	if err != nil {
		return "", err
	}

	if results, ok := txResult.OperationResults(); ok && len(results) > 0 {
		operationResult := results[0].MustTr().CreateClaimableBalanceResult
		return xdr.MarshalHex(operationResult.BalanceId)
	}

try:
  aAccount = server.load_account(A.public_key)
except NotFoundError:
  raise Exception(f"Failed to load account")

# Create a claimable balance with our two above-described conditions.
bCanClaim = ClaimPredicate.predicate_before_relative_time(60)

soon = int(time.time() + 60)
aCanClaim = ClaimPredicate.predicate_not(
  ClaimPredicate.predicate_before_absolute_time(
    soon
  )
)

# Create the operation and submit it in a transaction.
claimableBalanceEntry = CreateClaimableBalance(
  asset = Asset.native(),
  amount = "64",
  claimants = [
    Claimant(
      destination = B.public_key,
      predicate = bCanClaim
    ),
    Claimant(
      destination = A.public_key,
      predicate = aCanClaim
    )
  ]
)

transaction = (
  TransactionBuilder (
    source_account = aAccount,
    network_passphrase = Network.TESTNET_NETWORK_PASSPHRASE,
    base_fee = Network.MIN_BASE_FEE
  )
  .append_operation(claimableBalanceEntry)
  .set_timeout(180)
  .build()
)

transaction.sign(A)
try:
  txResponse = server.submit_transaction(transaction)
  print("Claimable balance created!")
except (BadRequestError, BadResponseError) as err:
  print(f"Tx submission failed: {err}")

Retrieval​

At this point, the ClaimableBalanceEntry exists in the ledger, but we’ll need its client balance ID to claim it, which can be done in several ways:

  1. The submitter of the entry (A\mathcal{A}) can retrieve the client balance ID before submitting the transaction.
  2. The submitter parses the XDR of the transaction result’s operations.
  3. Someone queries the list of claimable balances.

Either party could also check the /effects of the transaction or query /claimable_balances with different filters in Horizon. Note that while (1) may be unavailable in some SDKs, as it’s just a helper, the other methods are universal.

# Method 1: Suppose `tx` comes from the transaction built above.
#           Notice that this can be done *before* submission.
#           Use zero for `CreateClaimableBalance` first op.
clientBalanceID = tx.get_claimable_balance_id(0)
print(f"Balance ID (1): {clientBalanceID}")

# Method 2: Suppose `txResponse` comes from the transaction submission
# above.
txResult = TransactionResult.from_xdr(txResponse["result_xdr"])
results = txResult.result.results

# We look at the first result since our first (and only) operation
# in the transaction was the CreateClaimableBalanceOp.
operationResult = results[0].tr.create_claimable_balance_result
clientBalanceID = operationResult.balance_id.to_xdr_bytes().hex()
print(f"Balance ID (2): {clientBalanceID}")

# Method 3: Account B could alternatively do something like:
try:
  balances = (
    server
    .claimable_balances()
    .for_claimant(B.public_key)
    .limit(1)
    .order(desc = True)
    .call()
  )
except (BadRequestError, BadResponseError) as err:
  print(f"Claimable balance retrieval failed: {err}")

clientBalanceID = balances["_embedded"]["records"][0]["id"]
print(f"Balance ID (3): {clientBalanceID}")

Claiming​

With the client balance ID acquired, either B\mathcal{B} or A\mathcal{A} can actually submit a claim, depending on which predicate is fulfilled. We’ll assume here that a minute has passed, so A\mathcal{A} just reclaims the balance entry.

tx = (
  TransactionBuilder(
    source_account = aAccount,
    network_passphrase = Network.TESTNET_NETWORK_PASSPHRASE,
    base_fee = server.fetch_base_fee()
  )
  .append_operation(
    ClaimClaimableBalance(
      balance_id = clientBalanceID
    )
  )
  .set_timeout(180)
  .build()
)

tx.sign(A)
try:
  txResponse = server.submit_transaction(tx)
  print(f"{A.public_key} claimed {clientBalanceID}")
except (BadRequestError, BadResponseError) as err:
  print(f"Tx submission failed: {err}")

And that’s it! Since we opted for the reclaim path, A\mathcal{A} should have the same balance as what it started with (minus fees), and B\mathcal{B} should be unchanged.

Guides in this category: