ibc-engine-scope-of-work.md

S.o.W: Supporting Entire Cosmos Network for KDF Swaps

Currently KDF only supports swaps on two Cosmos networks: IRIS and Nucleus (which is our own network running on testnet). To swap native ATOM, you would need to send native ATOM to the IRIS network through an IBC channel, swap it there, and then send the resulting IBC asset back to the ATOM network to convert it into a native token. This process is both complicated and risky for users to perform manually, especially when selecting the IBC channel. If users pick a malicious or unsafe channel, they could lose their funds.

This work aims to automate this by doing IBC wrapping and unwrapping logics automatically with various security validations (e.g., adding restrictions and validations on IBC channel selection logic). KDF will either use a trusted IBC channel or notify the user that a trusted channel cannot be found. Users will still have the option to manually force KDF to use specific channels, but they will assume responsibility for the outcome.

How it works?

1. Bob places an order with ATOM for ETH

• Check IRIS balance: Making sure there is enough IRIS to cover the IBC wrapping fees and execution.

  • If Bob has enough balance, proceed to the next step.
  • If Bob does not have enough balance, the operation fails.

• Did Bob provide an IBC channel manually?

  • Yes → Use the provided IBC channel (Bob assumes responsibility).
  • No → Find an IBC channel from the coins file.
    • If a valid channel is found, proceed to Validate IBC channel.
    • If no channel is found, the operation fails.

• Validate the IBC channel: Check if the channel meets security and reliability requirements (e.g., its activity duration, successful operations, and total asset volume).

  • If the validation fails, the operation fails.
  • If the validation succeeds, lock the IRIS for the IBC wrapping process.

• Create the order: Generate the swap order using the validated IBC channel.

---

2. Alice wants to swap her ETH for ATOM

• Check IRIS balance: Making sure there is enough IRIS to cover the IBC unwrapping fees and execution.

  • If Alice has enough balance, proceed to the next step.
  • If Alice does not have enough balance, the operation fails.

• Did Alice provide an IBC channel manually?

  • Yes → Use the provided IBC channel (Alice assumes responsibility).
  • No → Find an IBC channel from the coins file.
    • If a valid channel is found, proceed to Validate IBC channel.
    • If no channel is found, the operation fails.

• Validate the IBC channel: Check if the channel meets security and reliability requirements.

  • If the validation fails, the operation fails.
  • If the validation succeeds, lock the IRIS for the IBC unwrapping process.

• Place the taker request: Alice submits her request to take the order.

• Run the swap: Execute the swap between Alice and Bob through the KDF platform.

• Unwrap IBC asset: Send the swapped asset from the IRIS network back to the ATOM network using the validated IBC channel.

Note: In case of swap errors IBC operations will be recovered whenever possible.

Unclear Items (but not blockers)

1. When should native assets be wrapped: during order creation or when the swap is initiated?
2. If an order fails due to issues on the other side, should the recipient pay the wrapping costs or should the maker always cover the IBC costs for both sides, even if the operation is successful?

Blockers

This PR needs to be completed before proceeding with this implementation.

When should native assets be wrapped: during order creation or when the swap is initiated?

Ideally, when swap is initiated but we have to be careful with timeouts during swaps.

If an order fails due to issues on the other side, should the recipient pay the wrapping costs or should the maker always cover the IBC costs for both sides, even if the operation is successful?

The side that is using Cosmos whether maker or taker will pay the wrapping/unwrapping costs at this stage of the implementation. Covering costs for failing swaps is another issue that has to be addressed globally first for all protocols.

KomodoPlatform/komodo-defi-framework#2298 needs to be completed before proceeding with this implementation.

Is it infra that is blocking this PR?

Is it infra that is blocking this PR?

Yeah, that was blocked due to infra needs (we need bunch of COSMOS nodes on different networks to support them on Nucleus as IBC assets) for very long time. I am planning to skip Nucleus on that work to avoid that blocker.