Skip to content

Commit ce6b5e3

Browse files
fasskofassko
committed
feat(docs): adds redemption default guide, explains redemption, describes redemption requested event
1 parent 214edea commit ce6b5e3

File tree

4 files changed

+139
-8
lines changed

4 files changed

+139
-8
lines changed

‎docs/fassets/3-redemption.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ This is the summary of the redemption process:
5555

5656
Agents have a limited time to pay the redeemer on the underlying chain.
5757
The amount of time is defined by the last block and the last timestamp on the underlying chain.
58-
If the payment is not made in time, the redeemer has to prove nonpayment to be compensated.
59-
After the redeemer presents the nonpayment proof, he is paid with the agent's collateral plus a _redemption default premium_.
58+
If the payment is not made in time, the redeemer has to prove [payment non existence](/fdc/attestation-types/referenced-payment-nonexistence) to be compensated.
59+
After the redeemer presents the payment non existence proof, he is paid with the agent's collateral plus a _redemption default premium_.
6060
The premium is intended to encourage the agent to complete redemptions by paying with the underlying asset instead of collateral.
6161

6262
If a payment fails and the failed transaction is recorded on the underlying chain, the agent must submit a proof of failed payment.
@@ -82,8 +82,8 @@ If the agent does not report the failed payment in time, anyone (including the e
8282

8383
During step 4 above, if any agent does not pay on the underlying chain, the redeemer completes the following procedure separately for each nonpaying agent:
8484

85-
1. The redeemer obtains a proof of nonpayment from the Flare Data Connector.
86-
2. The redeemer presents the nonpayment proofs to the FAssets system, which triggers a redemption failure.
85+
1. The redeemer obtains a proof of payment non existence from the Flare Data Connector.
86+
2. The redeemer presents the payment non existence proofs to the FAssets system, which triggers a redemption failure.
8787
3. The redeemer is paid with collateral, according to the current price plus a premium.
8888
4. FAssets are overcollateralized, so, even after paying the redeemer with a premium, a remainder is released.
8989
This remainder is derived by the [system-wide collateral ratio settings](/fassets/collateral#system-wide-thresholds) specified by governance.
@@ -94,7 +94,7 @@ During step 4 above, if any agent does not pay on the underlying chain, the rede
9494
### Unresponsive redeemer
9595

9696
After a redemption nonpayment, the redeemer might not report the failure for some reason.
97-
In this case, the agent or the executor can present a nonpayment proof, and the redeemer receives collateral plus a premium.
97+
In this case, the agent or the executor can present a payment non existence proof, and the redeemer receives collateral plus a premium.
9898
After this operation, the underlying backing collateral and the remaining local collateral are released.
9999

100100
### Unresponsive agent
@@ -108,7 +108,7 @@ After enough time for the agent to present the proof has elapsed, anyone, includ
108108
### Expired proof
109109

110110
Proofs provided by the Flare Data Connector are available for only 24 hours, approximately.
111-
If neither the redeemer, the agent, nor the executor presents the proof of payment or nonpayment within 24 hours, the regular redeeming process cannot continue, and the agent's collateral could be locked indefinitely.
111+
If neither the redeemer, the agent, nor the executor presents the proof of payment or payment non existence within 24 hours, the regular redeeming process cannot continue, and the agent's collateral could be locked indefinitely.
112112

113113
The procedure to recover this collateral is the same as the procedure in the minting case.
114114

‎docs/fassets/developer-guides/10-fassets-redemption-default.mdx‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Monitor Redemptions & Execute Defaults
3+
tags: [intermediate, fassets]
4+
slug: fassets-redemption-default
5+
description: Learn how to monitor and handle redemption non-payment scenarios
6+
keywords: [fassets, flare-network]
7+
sidebar_position: 10
8+
---
9+
10+
## Overview
11+
12+
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 that is defined by the [operational parameters](/fassets/operational-parameters).
13+
14+
This guide explains:
15+
16+
- How to **observe the redemption deadline**.
17+
- What parameters to use (`underlyingSecondsForPayment`, `underlyingBlocksForPayment`)
18+
- How to **handle agent failure** by calling [`redemptionPaymentDefault`](/fassets/reference/IAssetManager#redemptionpaymentdefault).
19+
20+
## Prerequisites
21+
22+
- Basic understanding of [FAssets system](/fassets/overview).
23+
- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts) package.
24+
25+
## Key Operational Parameters
26+
27+
| Parameter | Unit | Purpose |
28+
| ----------------------------- | ------- | ------------------------------------------------------------------------------------ |
29+
| `underlyingSecondsForPayment` | seconds | The minimum time allowed for an agent to pay for a redemption. |
30+
| `underlyingBlocksForPayment` | blocks | The number of underlying blocks during which the agent can pay the underlying value. |
31+
32+
Both values are defined per asset in the FAssets system and can be fetched from the [Asset Manager contract](/fassets/developer-guides/fassets-settings-solidity).
33+
34+
## Monitoring the Redemption Window
35+
36+
When a redemption is created, the [`RedemptionRequested`](/fassets/reference/IAssetManagerEvents#redemptionrequested) event is emitted by the Asset Manager contract.
37+
38+
From this event, you can obtain the following:
39+
40+
- `requestId` - unique identifier for the redemption.
41+
- `agentVault` - the agent vault responsible for payment.
42+
- `redeemer` - address requesting redemption.
43+
- `underlyingAddress` - the destination address on the underlying chain.
44+
- `paymentReference` - a unique hash for proof tracking.
45+
- `firstUnderlyingBlock` - the first underlying block to submit payment.
46+
- `lastUnderlyingBlock` - the last underlying block to submit payment.
47+
- `lastUnderlyingTimestamp` — the **deadline** on the underlying chain for submitting the redemption payment.
48+
49+
You should wait until this deadline is passed and then check whether the agent has paid the redemption payment in the underlying chain.
50+
The [`RedemptionPaymentCompleted`](/fassets/reference/IAssetManagerEvents#redemptionpaymentcompleted) event is emitted by the Asset Manager contract when the redemption payment is completed.
51+
52+
## Handling Non-Payment
53+
54+
If the agent fails to pay the redemption payment in the underlying chain, the redeemer or the executor can start the redemption default process.
55+
56+
### Generate the Proof of Payment Non-Existence
57+
58+
With information from the [`RedemptionRequested`](/fassets/reference/IAssetManagerEvents#redemptionrequested) event, you can generate the attestation request for the [ReferencedPaymentNonexistence](/fdc/attestation-types/referenced-payment-nonexistence) attestation type.
59+
60+
Use the following parameters:
61+
62+
- `minimalBlockNumber`: The starting block number of the search range, which is the value of `firstUnderlyingBlock`.
63+
- `deadlineBlockNumber`: The block number to include as the end of the search range, which is the value of `lastUnderlyingBlock`.
64+
- `deadlineTimestamp`: The timestamp to include as the end of the search range, which is the value of `lastUnderlyingTimestamp`.
65+
- `destinationAddressHash`: The standard hash of the address where the payment was expected, which is the value of `underlyingAddress`.
66+
- `amount`: The required payment amount in minimal units, which is the value of `valueUBA`.
67+
- `standardPaymentReference`: The specific payment reference that should have been included, which is the value of `paymentReference`.
68+
- `checkSourceAddresses`: Not used in case of XRP Ledger, always set to false.
69+
- `sourceAddressesRoot`: Not used in case of XRP Ledger, always set to zero address.
70+
71+
With this information, create the attestation request with the Flare Data Connector and wait for the attestation request to be confirmed.
72+
73+
### Execute the Redemption Default
74+
75+
After the attestation request is confirmed, you can retrieve the proof of payment non-existence of the redemption payment on the XRP Ledger.
76+
77+
The redeemer or executor can execute the redemption default process by calling the [`redemptionPaymentDefault`](/fassets/reference/IAssetManager#redemptionpaymentdefault) function on the Asset Manager contract.
78+
79+
This function requires two parameters:
80+
81+
- `_proof`: The proof of payment non-existence of the redemption payment on the XRP Ledger.
82+
- `_redemptionRequestId`: The request ID of the redemption request.
83+
84+
It does the following:
85+
86+
- Checks if the proof of payment non-existence is valid.
87+
- Enough time has passed since the redemption request was created.
88+
- Executes the compensation payment to the redeemer or the executor from the agent's collateral.
89+
- Releases the agent's locked collateral.
90+
- Emits [`RedemptionDefaulted`](/fassets/reference/IAssetManagerEvents#redemptiondefault) event.
91+
92+
## Summary
93+
94+
In this guide, you learned how to monitor redemption requests and handle agent payment failures in the FAssets system:
95+
96+
- **Monitor deadlines**: Track the [`RedemptionRequested`](/fassets/reference/IAssetManagerEvents#redemptionrequested) event and wait for the payment deadline to pass.
97+
- **Generate proof**: Create a [`ReferencedPaymentNonexistence`](/fdc/attestation-types/referenced-payment-nonexistence) attestation using the [Flare Data Connector](/fdc/overview).
98+
- **Execute default**: Call [`redemptionPaymentDefault`](/fassets/reference/IAssetManager#redemptionpaymentdefault) to trigger compensation from the agent's collateral.
99+
100+
This process ensures redeemers can recover their funds when agents fail to fulfill payment obligations.
101+
102+
:::tip Next Steps
103+
To continue your FAssets development journey, you can:
104+
105+
- Understand how to [redeem FXRP](/fassets/developer-guides/fassets-redeem)
106+
- Learn how to [mint FXRP](/fassets/developer-guides/fassets-mint)
107+
- Explore [FAssets system settings](/fassets/operational-parameters)
108+
:::

‎docs/fassets/developer-guides/7-fassets-redeem.mdx‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -331,8 +331,16 @@ You can read the full event description [here](/fassets/reference/IAssetManagerE
331331

332332
The FAssets agent should perform the redemption, and the user must retrieve the redeemed assets from the agent.
333333

334-
If the agent is unable to redeem the assets on the underlying chain in the specified time.
335-
In that case, the user can execute the [`redemptionPaymentDefault`](/fassets/reference/IAssetManager#redemptionpaymentdefault) function to receive compensation from the agent's collateral.
334+
These [operational parameters](/fassets/operational-parameters) define the timeframe within which the agent must complete the redemption payment:
335+
336+
- `underlyingBlocksForPayment`: The number of underlying blocks during which the agent can pay the underlying value.
337+
- `underlyingSecondsForPayment`: The minimum time allowed for an agent to pay for a redemption.
338+
339+
If the agent is unable to pay the redemption payment in the specified time, the redeemer can:
340+
341+
1. Make a proof of [payment non existence](/fdc/attestation-types/referenced-payment-nonexistence) using the [Flare Data Connector](/fdc/overview).
342+
2. Execute the [`redemptionPaymentDefault`](/fassets/reference/IAssetManager#redemptionpaymentdefault) function and present the proof of payment non existence to the FAssets system, which triggers a redemption failure.
343+
3. The redeemer receives collateral plus a premium.
336344

337345
## Next Steps
338346

‎docs/fassets/reference/IAssetManagerEvents.mdx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,21 @@ All events related to the FAssets redemption process, including redemption reque
167167

168168
An event is emitted when the redeemer starts the redemption process.
169169

170+
Parameters:
171+
172+
- `agentVault`: Address of the agent vault.
173+
- `redeemer`: Address of the redeemer.
174+
- `requestId`: Unique identifier for the redemption request.
175+
- `paymentAddress`: Address to which the agent must transfer the redeemed amount on the underlying chain.
176+
- `valueUBA`: Amount of FAssets to redeem.
177+
- `feeUBA`: Fee for the redemption.
178+
- `firstUnderlyingBlock`: First underlying block to submit payment.
179+
- `lastUnderlyingBlock`: Last underlying block to submit payment.
180+
- `lastUnderlyingTimestamp`: Deadline on the underlying chain for submitting the redemption payment.
181+
- `paymentReference`: Reference for payment that will be used to track the redemption payment.
182+
- `executor`: Address of the executor that is allowed to execute the redemption default.
183+
- `executorFeeNatWei`: Fee for the executor in NAT wei.
184+
170185
```solidity
171186
event RedemptionRequested(
172187
address indexed agentVault,

0 commit comments

Comments
 (0)