Skip to main content

Monitor Redemptions & Execute Defaults

Overview​

In the FAssets system, once a redeemer submits a redemption request, the assigned agent must send the underlying asset (e.g., XRP) to the redeemer within a specific time defined in the operational parameters.

This guide explains:

  • How to observe the redemption deadline.
  • What parameters to use (underlyingSecondsForPayment, underlyingBlocksForPayment).
  • How to handle agent failure by calling redemptionPaymentDefault.

Prerequisites​

Key Operational Parameters​

The FAssets system has specific operational parameters that control the timing of redemption payments. These parameters define both the minimum time window and block range during which an agent must complete the underlying payment.

ParameterUnitPurpose
underlyingSecondsForPaymentsecondsThe minimum time allowed for an agent to pay for a redemption.
underlyingBlocksForPaymentblocksThe number of underlying blocks during which the agent can pay the underlying value.

Both values are defined per asset in the FAssets system and can be fetched from the Asset Manager contract.

Monitoring the Redemption Window​

When a redemption is created, the RedemptionRequested event is emitted by the Asset Manager contract.

From this event, you can obtain the following:

  • requestId: unique identifier for the redemption.
  • agentVault: the agent vault responsible for the payment.
  • redeemer: address requesting redemption.
  • underlyingAddress: the destination address on the underlying chain.
  • paymentReference: a unique hash for proof tracking.
  • firstUnderlyingBlock: the first underlying block to submit payment.
  • lastUnderlyingBlock: the last underlying block to submit payment.
  • lastUnderlyingTimestamp: the deadline on the underlying chain for submitting the redemption payment.

Wait until the deadline passes, then check whether the agent made the redemption payment on the underlying chain. These two values work together as a dual safety mechanism: lastUnderlyingBlock ensures the payment happens within a reasonable number of blocks, while lastUnderlyingTimestamp guarantees the payment occurs within a reasonable amount of time. Both constraints must be satisfied for the payment to be considered valid, providing robust protection against timing-based attacks.

The RedemptionPerformed event is emitted by the Asset Manager contract when the redemption payment is completed.

info

The simplest way to observe if a redemption payment has been made is to use the xrpl Node.js package to monitor incoming transactions to the underlyingAddress (the redeemer's address on the underlying chain). Wait until the underlyingSecondsForPayment and underlyingBlocksForPayment deadlines pass, then check if any incoming transactions match the expected redemption amount. To verify the payment is for the correct redemption, compare the memo data in the XRP transaction to the paymentReference from the RedemptionRequested event.

Handling Non-Payment​

If the agent fails to complete the redemption in the XRP Ledger, the redeemer or the executor can initiate the redemption default process.

Generate the Proof of Payment Non-Existence​

With the information from the RedemptionRequested event, you can generate the attestation request for the ReferencedPaymentNonexistence attestation type.

Use the following parameters:

  • minimalBlockNumber: The starting block number of the search range, which is the value of firstUnderlyingBlock.
  • deadlineBlockNumber: The block number to include as the end of the search range, which is the value of lastUnderlyingBlock.
  • deadlineTimestamp: The timestamp to include as the end of the search range, which is the value of lastUnderlyingTimestamp.
  • destinationAddressHash: The standard hash of the address where the payment was expected, which is the value of underlyingAddress.
  • amount: The required payment amount in minimal units, which is the value of valueUBA.
  • standardPaymentReference: The specific payment reference that should have been included, which is the value of paymentReference.
  • checkSourceAddresses: Not used in case of XRP Ledger, always set to false.
  • sourceAddressesRoot: Not used in case of XRP Ledger, always set to zero address.

Create the attestation request with the Flare Data Connector and wait for the attestation request to be confirmed.

info

Check the ReferencedPaymentNonexistence attestation type for more details, and the FDC by hand guide for more information on how to create the attestation request.

Execute the Redemption Default​

After the attestation request is confirmed, you can retrieve the proof of payment for the non-existence of the redemption payment on the XRP Ledger.

The redeemer or the executor can execute the redemption default process by calling the redemptionPaymentDefault function on the AssetManager contract.

This function requires two parameters:

  • _proof: The proof of payment non-existence from the FDC of the redemption payment on the XRP Ledger.
  • _redemptionRequestId: The request ID of the redemption request from the RedemptionRequested event.

It does the following:

  • Checks if the proof of payment non-existence is valid.
  • Verifies that both the underlyingSecondsForPayment and underlyingBlocksForPayment deadlines have passed.
  • Executes the compensation payment to the redeemer or the executor from the agent's collateral.
  • Releases the agent's locked collateral.
  • Emits the RedemptionDefaulted event.

Summary​

In this guide, you learned how to monitor redemption requests and handle agent payment failures in the FAssets system:

This process ensures redeemers can recover their funds when agents fail to meet their payment obligations.

Next Steps

To continue your FAssets development journey, you can: