Legacy Payment Helpers

DEPRECATED

claim, combine, split, and splitMany are deprecated. They are no longer methods on Issuer. They remain available as standalone functions exported from @agoric/ertp/src/legacy-payment-helpers.js (not re-exported from the package's main entry point), each parameterized by a recoveryPurse used to recover a Payment if the helper fails partway through.

Each helper first deposits its input Payment(s) into the recoveryPurse argument before withdrawing the result. If a helper fails after depositing but before it can withdraw and return the result, no assets are lost: they remain in recoveryPurse, and can also be recovered from that purse's recovery set if the purse is itself lost track of.

combine is not failure-atomic in one respect: if it fails partway through, some of the input Payments may already have been consumed. Even then, no assets are lost; they end up in recoveryPurse.

import {
  claim,
  combine,
  split,
  splitMany,
} from '@agoric/ertp/src/legacy-payment-helpers.js';

claim(recoveryPurse, srcPaymentP, optAmountShape?)

• recoveryPurse: Purse
• srcPaymentP: ERef<Payment>
• optAmountShape: Pattern - Optional.
• Returns: Promise<Payment>

Transfers all digital assets from srcPaymentP to a new Payment, consuming the original. If the optAmountShape argument is passed, the source Payment's amount must match it, or the deposit throws and no Payment is withdrawn.

const newPayment = await claim(
  recoveryPurse,
  originalPayment,
  amountToTransfer,
);

combine(recoveryPurse, srcPaymentsPs, optTotalAmount?)

• recoveryPurse: Purse
• srcPaymentsPs: Array<ERef<Payment>>
• optTotalAmount: Pattern - Optional.
• Returns: Promise<Payment>

Combines multiple Payments into one new Payment, depositing each into recoveryPurse as its promise resolves. If optTotalAmount is passed, the combined total must match it before the result is withdrawn.

const combinedPayment = await combine(recoveryPurse, harden(payments));

split(recoveryPurse, srcPaymentP, paymentAmountA)

• recoveryPurse: Purse
• srcPaymentP: ERef<Payment>
• paymentAmountA: Amount
• Returns: Promise<Payment[]>

Splits a single Payment into two new Payments, A and B, according to paymentAmountA, after depositing the source Payment into recoveryPurse.

const [paymentA, paymentB] = await split(
  recoveryPurse,
  oldPayment,
  AmountMath.make(quatloosBrand, 10n),
);

splitMany(recoveryPurse, srcPaymentP, amounts)

• recoveryPurse: Purse
• srcPaymentP: ERef<Payment>
• amounts: Array<Amount>
• Returns: Promise<Payment[]>

Splits a single Payment into multiple Payments, one per entry in amounts, after depositing the source Payment into recoveryPurse. If amounts doesn't add up to the source Payment's amount, the operation throws once the source has already been deposited into recoveryPurse.

const arrayOfNewPayments = await splitMany(
  recoveryPurse,
  oldPayment,
  harden(goodAmounts),
);