You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/fassets/3-redemption.mdx
+26-26Lines changed: 26 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,12 +34,12 @@ This is the summary of the redemption process:
34
34
35
35
4. Every agent pays the redeemer on the underlying chain and includes the payment reference in the memo field of the payment transaction.
36
36
37
-
Agents can pay the redemption from their own address they control on the underlying chain.
37
+
Agents can pay the redemption from their own address, which they control on the underlying chain.
38
38
It does not need to be the same address where they receive minting payments.
39
39
40
40
5. After the payment is finalized, the agent uses the [FDC](/fdc/overview) to prove the payment and obtain a payment proof.
41
41
42
-
6. The agent (or, in Core Vault and certain flows, the **executor**) presents the payment proof to the FAssets system, which issues a **redemption ticket**.
42
+
6. The agent (or, in Core Vault and specific flows, the **executor**) presents the payment proof to the FAssets system, which issues a **redemption ticket**.
43
43
44
44
The executor role is responsible for ensuring that the system can finalize redemptions even if the agent is unresponsive or if the flow is managed by a central entity (such as the Core Vault executor).
45
45
@@ -54,92 +54,92 @@ This is the summary of the redemption process:
54
54
## Redemption-Payment Failure
55
55
56
56
Agents have a limited time to pay the redeemer on the underlying chain.
57
-
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_.
57
+
The last block and the last timestamp on the underlying chain define the amount of time.
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_.
60
60
The premium is intended to encourage the agent to complete redemptions by paying with the underlying asset instead of collateral.
61
61
62
-
If a payment fails and the failed transaction is recorded on the underlying chain, the agent must submit a proof of failed payment.
62
+
If a payment fails and the failed transaction is recorded on the underlying chain, the agent must submit proof of the failed payment.
63
63
In this way, the gas costs of the failed transaction can be accounted for by the FAssets system.
64
-
If the transaction was not recorded, then no gas was spent and reporting is not necessary.
64
+
If the transaction was not recorded, then no gas was spent, and reporting is not necessary.
65
65
66
66
If the agent does not report the failed payment in time, anyone (including the executor) can report the failed payment and receive a reward from the agent's vault.
67
67
68
68
:::info
69
69
70
-
When payment fails because of the redeemer, the agent can obtain a proof of the failed payment from the Flare Data Connector and present it to the FAssets system.
70
+
When payment fails because of the redeemer, the agent can obtain proof of the failed payment from the Flare Data Connector and present it to the FAssets system.
71
71
The agent's obligation is then fulfilled, and he can keep both the collateral and the underlying.
72
72
73
73
Two different proofs can be used:
74
74
75
75
* Proof of invalid address, due to a wrong syntax or checksum, for example.
76
76
* Proof of blocked payment: Even if the address is valid, it might contain a contract that blocks the payment.
77
-
This can only happen on underlying networks supporting smart contracts.
77
+
This can only occur on underlying networks that support smart contracts.
78
78
79
-
The agent must still try to pay and, if the payment is blocked, the agent can request this proof from the Flare Data Connector and present it to the FAssets system.
79
+
The agent must still try to pay, and if the payment is blocked, the agent can request this proof from the Flare Data Connector and present it to the FAssets system.
80
80
81
81
:::
82
82
83
83
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:
84
84
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.
87
87
3. The redeemer is paid with collateral, according to the current price plus a premium.
88
88
4. FAssets are overcollateralized, so, even after paying the redeemer with a premium, a remainder is released.
89
-
This remainder is derived by the [system-wide collateral ratio settings](/fassets/collateral#system-wide-thresholds) specified by governance.
89
+
This remainder is derived from the [system-wide collateral ratio settings](/fassets/collateral#system-wide-thresholds) specified by governance.
90
90
5. The underlying assets backing the redeemed FAssets are marked as free and can be withdrawn by the agent later.
91
91
92
92
## Edge Cases
93
93
94
94
### Unresponsive redeemer
95
95
96
96
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.
98
98
After this operation, the underlying backing collateral and the remaining local collateral are released.
99
99
100
100
### Unresponsive agent
101
101
102
102
After a successful payment, the agent might not present the payment proof (redemption ticket).
103
103
104
104
Because the agent has already paid, the redeemer is not affected.
105
-
However, the system still requires the payment proof to correctly track the agent's balance on the underlying chain.
106
-
After enough time for the agent to present the proof has elapsed, anyone, including the executor, can present the payment proof and receive collateral from the agent's vault as a reward.
105
+
However, the system still requires the payment proof to track the agent's balance on the underlying chain correctly.
106
+
After enough time for the agent to present the proof has elapsed, anyone, including the executor, can show the payment proof and receive collateral from the agent's vault as a reward.
107
107
108
108
### Expired proof
109
109
110
-
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.
110
+
Proofs provided by the Flare Data Connector are available for approximately 24 hours.
111
+
If neither the redeemer, the agent, nor the executor presents the proof of payment or payment non-existence within 24 hours, the regular redemption process cannot continue, and the agent's collateral could be locked indefinitely.
112
112
113
113
The procedure to recover this collateral is the same as the procedure in the minting case.
114
114
115
115
## Redemption Fee
116
116
117
-
The redemption fee is the amount of the underlying asset that the agent can keep for doing the redemption.
118
-
This fee is meant only to cover the agent's transaction fee on the underlying chain, so it is not shared with the collateral pool.
117
+
The redemption fee is the amount of the underlying asset that the agent retains upon redemption.
118
+
This fee is intended solely to cover the agent's transaction fee on the underlying chain, and therefore, it is not shared with the collateral pool.
119
119
The fee percentage is defined by governance, is the same for all agents, and is typically smaller than the minting fee.
120
120
121
-
Governance calculates the percentage so that the fee to redeem 1 lot pays for a typical transaction fee on the underlying chain.
122
-
Therefore, when larger amounts on a single address are redeemed, the agent accrues some extra fees because the underlying fee for small and large transactions is the same.
123
-
However, when underlying fees are very high, the agent might still lose funds when a redemption for a small amount, such as 1 lot, is made.
121
+
Governance calculates the percentage so that the fee to redeem one lot pays for a typical transaction fee on the underlying chain.
122
+
Therefore, when larger amounts are redeemed at a single address, the agent accrues additional fees because the underlying fee for both small and large transactions is the same.
123
+
However, when underlying fees are very high, the agent might still lose funds when a redemption for a small amount, such as one lot, is made.
124
124
If this situation occurs frequently, governance will increase the redemption-fee percentage.
125
125
126
126
## Self-redemption
127
127
128
128
Agents can also act as users and redeem FAssets from their own vaults.
129
129
This process is called self-redemption or self-closing, and it is simplified because payment on the underlying chain is not required.
130
130
131
-
As shown in the following process, agents can self-redeem for any reason, including to stop liquidations because it reduces the amount of FAssets the agent is backing.
131
+
As shown in the following process, agents can self-redeem for any reason, including to prevent liquidations, as it reduces the amount of FAssets the agent is backing.
132
132
133
133
1. An agent sends FAssets to their account.
134
134
2. FAssets are burned.
135
135
3. The collateral that was backing those assets is released.
136
136
4. The underlying collateral is released and can be withdrawn from the underlying address later.
137
137
138
-
The self-redeemed amount is not limited to a positive integer of lots and can be less than 1 lot, which makes self-closing ideal for redeeming an agent's dust.
138
+
The self-redeemed amount is not limited to a positive integer of lots and can be less than one lot, which makes self-closing ideal for redeeming an agent's dust.
139
139
140
140
:::tip[What's next]
141
141
142
-
Learn more about the different components and processes involved in FAssets - [collateral](/fassets/collateral), [minting](/fassets/minting), [liquidations](/fassets/liquidation) and [Core Vault](/fassets/core-vault).
142
+
Learn more about the different components and processes involved in FAssets - [collateral](/fassets/collateral), [minting](/fassets/minting), [liquidations](/fassets/liquidation), and [Core Vault](/fassets/core-vault).
143
143
144
144
For developer resources, explore our [FXRP address](/fassets/developer-guides/fassets-fxrp-address), [minting](/fassets/developer-guides/fassets-mint), and [redemption](/fassets/developer-guides/fassets-redeem) guides to get started with FAssets integration.
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 defined in 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 the [FAssets system](/fassets/overview).
|`underlyingSecondsForPayment`| seconds | The minimum time allowed for an agent to pay for a redemption. |
33
+
|`underlyingBlocksForPayment`| blocks | The number of underlying blocks during which the agent can pay the underlying value. |
34
+
35
+
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).
36
+
37
+
## Monitoring the Redemption Window
38
+
39
+
When a redemption is created, the [`RedemptionRequested`](/fassets/reference/IAssetManagerEvents#redemptionrequested) event is emitted by the Asset Manager contract.
40
+
41
+
From this event, you can obtain the following:
42
+
43
+
-`requestId`: unique identifier for the redemption.
44
+
-`agentVault`: the agent vault responsible for the payment.
45
+
-`redeemer`: address requesting redemption.
46
+
-`underlyingAddress`: the destination address on the underlying chain.
47
+
-`paymentReference`: a unique hash for proof tracking.
48
+
-`firstUnderlyingBlock`: the first underlying block to submit payment.
49
+
-`lastUnderlyingBlock`: the last underlying block to submit payment.
50
+
-`lastUnderlyingTimestamp`: the **deadline** on the underlying chain for submitting the redemption payment.
51
+
52
+
Wait until the deadline passes, then check whether the agent made the redemption payment on the underlying chain.
53
+
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.
54
+
Both constraints must be satisfied for the payment to be considered valid, providing robust protection against timing-based attacks.
55
+
56
+
The [`RedemptionPerformed`](/fassets/reference/IAssetManagerEvents#redemptionperformed) event is emitted by the Asset Manager contract when the redemption payment is completed.
57
+
58
+
:::info
59
+
The simplest way to observe if a redemption payment has been made is to use the [xrpl](https://www.npmjs.com/package/xrpl) Node.js package to monitor incoming transactions to the `underlyingAddress` (the redeemer's address on the underlying chain).
60
+
Wait until the `underlyingSecondsForPayment` and `underlyingBlocksForPayment` deadlines pass, then check if any incoming transactions match the expected redemption amount.
61
+
To verify the payment is for the correct redemption, compare the memo data in the XRP transaction to the `paymentReference` from the `RedemptionRequested` event.
62
+
:::
63
+
64
+
## Handling Non-Payment
65
+
66
+
If the agent fails to complete the redemption in the XRP Ledger, the redeemer or the executor can initiate the redemption default process.
67
+
68
+
### Generate the Proof of Payment Non-Existence
69
+
70
+
With the 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.
71
+
72
+
Use the following parameters:
73
+
74
+
-`minimalBlockNumber`: The starting block number of the search range, which is the value of `firstUnderlyingBlock`.
75
+
-`deadlineBlockNumber`: The block number to include as the end of the search range, which is the value of `lastUnderlyingBlock`.
76
+
-`deadlineTimestamp`: The timestamp to include as the end of the search range, which is the value of `lastUnderlyingTimestamp`.
77
+
-`destinationAddressHash`: The standard hash of the address where the payment was expected, which is the value of `underlyingAddress`.
78
+
-`amount`: The required payment amount in minimal units, which is the value of `valueUBA`.
79
+
-`standardPaymentReference`: The specific payment reference that should have been included, which is the value of `paymentReference`.
80
+
-`checkSourceAddresses`: Not used in case of XRP Ledger, always set to false.
81
+
-`sourceAddressesRoot`: Not used in case of XRP Ledger, always set to zero address.
82
+
83
+
Create the attestation request with the Flare Data Connector and wait for the attestation request to be confirmed.
84
+
85
+
:::info
86
+
Check the [ReferencedPaymentNonexistence](/fdc/attestation-types/referenced-payment-nonexistence) attestation type for more details, and the [FDC by hand](/fdc/guides/fdc-by-hand) guide for more information on how to create the attestation request.
87
+
:::
88
+
89
+
### Execute the Redemption Default
90
+
91
+
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.
92
+
93
+
The redeemer or the executor can execute the redemption default process by calling the [`redemptionPaymentDefault`](/fassets/reference/IAssetManager#redemptionpaymentdefault) function on the AssetManager contract.
94
+
95
+
This function requires two parameters:
96
+
97
+
-`_proof`: The proof of payment non-existence from the FDC of the redemption payment on the XRP Ledger.
98
+
-`_redemptionRequestId`: The request ID of the redemption request from the `RedemptionRequested` event.
99
+
100
+
It does the following:
101
+
102
+
- Checks if the proof of payment non-existence is valid.
103
+
- Verifies that both the `underlyingSecondsForPayment` and `underlyingBlocksForPayment` deadlines have passed.
104
+
- Executes the compensation payment to the redeemer or the executor from the agent's collateral.
105
+
- Releases the agent's locked collateral.
106
+
- Emits the [`RedemptionDefaulted`](/fassets/reference/IAssetManagerEvents#redemptiondefault) event.
107
+
108
+
## Summary
109
+
110
+
In this guide, you learned how to monitor redemption requests and handle agent payment failures in the FAssets system:
111
+
112
+
-**Monitor the deadlines**: Track the [`RedemptionRequested`](/fassets/reference/IAssetManagerEvents#redemptionrequested) event and wait for the payment deadline to pass.
113
+
-**Generate proof**: Create a [`ReferencedPaymentNonexistence`](/fdc/attestation-types/referenced-payment-nonexistence) attestation using the [Flare Data Connector](/fdc/overview).
114
+
-**Execute default**: Call [`redemptionPaymentDefault`](/fassets/reference/IAssetManager#redemptionpaymentdefault) to trigger compensation from the agent's collateral.
115
+
116
+
This process ensures redeemers can recover their funds when agents fail to meet their payment obligations.
117
+
118
+
:::tip Next Steps
119
+
To continue your FAssets development journey, you can:
120
+
121
+
- Learn how to [mint FXRP](/fassets/developer-guides/fassets-mint)
122
+
- Understand how to [redeem FXRP](/fassets/developer-guides/fassets-redeem)
123
+
- Explore [FAssets system settings](/fassets/operational-parameters)
Copy file name to clipboardExpand all lines: docs/fassets/developer-guides/7-fassets-redeem.mdx
+10-2Lines changed: 10 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -331,8 +331,16 @@ You can read the full event description [here](/fassets/reference/IAssetManagerE
331
331
332
332
The FAssets agent should perform the redemption, and the user must retrieve the redeemed assets from the agent.
333
333
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.
0 commit comments