Implement asset conversion in transactions

[gitfelipegomes]

Context

Currently, Midaz supports transactions involving a single asset only. However, since the Ledger is a multi-asset system, we are implementing the ability to perform asset conversions during a transaction.

To facilitate this, Midaz will offer two methods for specifying conversion rates:

1. Providing conversion rates during transaction creation

This method is recommended as it allows Midaz to utilize the most up-to-date conversion rates available. When creating a transaction, the user must include the conversion rates for operations between the assets of the accounts involved. These rates will be used directly by Midaz for transaction processing.

2. Pre-registering conversion rates in the asset-rates table

This option is better suited for cases where the conversion rate between two assets is fixed. When creating a transaction, the user does not need to provide conversion rates. Instead, if a conversion is required, Midaz will query the asset-rates table to determine the appropriate conversion rates.

This method can also act as a fallback for the first option. For instance, if the conversion rate provider is unavailable at the time of transaction creation, Midaz can refer to the asset-rates table to ensure continuity.

Responsibilities and Error Handling

• The user is responsible for maintaining and updating the asset-rates table with accurate rates.
• If the required asset pair is not found in the asset-rates table, the transaction will be rejected, and an error will be returned to the user.

Requirements

1. Automatic reconciliation with external accounts

By default, conversions will be processed in external world. Consequently, Midaz must automatically create operations to reconcile the values of external accounts. This ensures consistency between the values received from external world and those stored in the Ledger’s accounts.

2. Dual option for the asset in the send field

For transactions involving multiple assets, the send field must support two scenarios:
1. Sending an amount in the asset of the source account.
2. Sending an amount in the asset of the destination account.

Midaz must determine whether to calculate the debit amount in the source account or the credit amount in the destination account based on the specified conversion rates.

3. Determination of Conversion Rate Lookup

Midaz will always use the asset specified in the send field as the origin (from) for conversion rate lookups. For example:

• When sending BRL to a USD account, Midaz will look up the conversion rate from BRL to USD.
• If the rate in this order (from: BRL, to: USD) is not found in the database, the transaction will fail.

4. Conversion Rate Processing Workflow

Midaz will follow the workflow below to process conversion rates:

1. Provided Rates in Transaction:

• If conversion rates are included in the transaction object, they will be used directly, ignoring the asset-rates table.
• All required conversion rates must be provided in the transaction. Partial rates will not be accepted.

2. Fallback to asset-rates Table:

• If conversion rates are not provided in the transaction object, Midaz will query the asset-rates table for the necessary rates.

3. Error Handling:

• If any required rate is not found (either in the transaction object or in the asset-rates table), the transaction will fail, and an error will be returned to the user.

[MartinezAvellan]

• If the RATE field is provided, should it be saved/updated in the database?
• Set rate fields on database operations
• The asset of the accounts in the from section must match the asset specified in the send command.
• Transactions with a rate do not allow accounts of type external.
• Only transactions involving two assets (1 rate) will be permitted.
  The rate will be optional:
• If the rate is not provided, it will be retrieved from the asset_rate table in the database, always in the direction {{asset_send}} -> {{asset_account_distribute}}.
  Exchanges performed must be reconciled with the external accounts of the assets:
• Credit the external account of the source asset (sale of the asset to the external world).
• Debit the external account of the destination asset (receipt of the exchanged value in the new asset, resulting from the previous sale).