Bonds and penalties

A merchant accepting a voucher offline can't see the payer's live vault balance. The bond is what protects them: funds the payer locks in their vault, which are used only when the payer breaks the rules.

Overspending#

If vouchers settle for more than the vault's balance, the program pays the shortfall from the bond and marks the vault as overspent. If the bond can't cover it either, the remainder is recorded as unpaid in the VoucherRedeemed event.

Within one settlement batch, earlier vouchers (by created_at) are paid first.

Double-spending#

A double-spend is when the payer signs two different vouchers with the same sequence number, for example to pay two merchants with the same money.

  1. The first voucher to settle is paid normally.
  2. The second is rejected with DoubleSpend.
  3. Its merchant calls claim_double_spend with the rejected voucher. The program confirms that a different voucher already used that sequence number, pays the merchant from the bond (up to the voucher amount), and freezes the vault's withdrawals.

A claim can only be made once per voucher. Vouchers still settle from the frozen vault's balance, so honest merchants who are still owed money keep getting paid.

Sizing the bond#

The bond is the most a merchant can count on if something goes wrong. Merchant apps can show how much of a payment the payer's bond would cover, and merchants can set their own offline limits against it.