FAsset Instructions

In this guide, we will take a closer look at the Flare Smart Accounts instructions related to FAssets. FAsset is a trustless, over-collateralized bridge between XRPL and the Flare chain. The FXRP is a token representation of XRP on the Flare chain. FAssets allow XRPL users to partake in Flare's DeFi ecosystem using their XRP assets, without exchanging them for the FLR token.

Several steps of the FAsset process are performed as transactions on the Flare chain, which requires users to hold FLR tokens for paying gas fees. The Flare Smart Accounts sidestep this by allowing XRPL users to trigger these actions through Payment transactions on XRPL. Thus, they eradicate completely the need for XRPL users to hold any non-XRPL assets.

You can learn more about the FAssets in the dedicated section.

The instructions fall under three types: FXRP, Firelight, and Upshift. Each type supports different instruction commands. The FXRP commands allow interaction with the base FAssets system, whereas Firelight and Upshift give access to actions pertaining to the corresponding vault architectures.

`00` FXRP

The commands of the FXRP type give access to base FAsset actions.

`01` Collateral reservation

Collateral reservation is the first step in the FAssets minting process. In anticipation of the transfer of XRP to the agent's underlying address on XRPL, a portion of its collateral is locked to prevent accidental under-collateralization. Since this action happens on the Flare chain, the gas fees need to be paid in the native FLR token.

The collateral reservation action reserves a value of lots of collateral in the agent vault with the agentVaultId. The MasterAccountController keeps a registry of agent vault addresses, and the agentVaultId corresponds to one of the keys of that registry.

The process is performed by an executor with executorFee (explained in the minting guide); it is defined by the MasterAccountController contract.

A collateral reservation payment reference is a 32-byte value:

byte representation of the instruction ID in the first byte:
- type ID 00 in the first nibble,
- command ID 01 in the second nibble,
byte representation of walletId in the second byte
byte representation of value in the next 10 bytes
byte representation of agentVaultId in the next two bytes
the remaining 18 bytes are ignored and can have an arbitrary value

Breakdown of bytes in payment reference for the collateral reservation action.

`02` Transfer

Transfer value of drops of FXRP to the recipientAddress. The FXRP is sent from the personal account that belongs to the XRPL address that sent the instruction, if the FXRP balance is sufficient.

A transfer payment reference is a 32-byte value:

byte representation of the instruction ID in the first byte:
- type ID 00 in the first nibble,
- command ID 01 in the second nibble,
byte representation of walletId in the second byte
byte representation of value in the next 10 bytes
recipientAddress in the remaining 20 bytes

Breakdown of bytes in payment reference for the transfer action.

`03` Redeem

Redemption is the process of converting FXRP back to XRP. A value of lots of FXRP are burned from the personal account belonging to the XRPL address that sent the instruction; and the same value of lots of XRP is returned to the user's XRPL account.

The process is performed by an executor with executorFee (explained in the minting guide); both of these are defined by the MasterAccountController contract.

A redeem payment reference is the 32-byte value:

byte representation of the instruction ID in the first byte:
- type ID 00 in the first nibble,
- command ID 02 in the second nibble,
byte representation of walletId in the second byte
byte representation of value in the next 10 bytes
the remaining 20 bytes are ignored and can have an arbitrary value

Breakdown of bytes in payment reference for the redeem action.

`01` Firelight

The commands of the Firelight type allow interaction with Firelight-type vaults.

`01` Collateral reservation and deposit

Reserve the collateral for value lots of FXRP with the agent's vault, registered with the agentVaultId with the MasterAccountController contract. When minting is completed, deposit value lots of FXRP into a Firelight-type vault at the address registered with the MasterAccountController contract with the vaultId. Essentially, this allows an XRPL user to signal intent for two actions at once; it is equivalent to sending a collateral reservation instruction first, and afterwards a deposit instruction. This cuts the total waiting time in half and reduces the total number of transactions by one.

A collateral reservation and deposit instruction payment reference is the 32-byte value:

byte representation of the instruction ID in the first byte:
- type ID 01 in the first nibble,
- command ID 01 in the second nibble,
byte representation of walletId in the second byte
byte representation of value in the next 10 bytes
byte representation of agentVaultId in the next 2 bytes
byte representation of vaultId in the next 2 bytes
the remaining 16 bytes are ignored and can have an arbitrary value

Breakdown of bytes in payment reference for the collateral reservation and deposit action.