From 6e16e5b2df9c9011ed757fb26798e89ec2755f2f Mon Sep 17 00:00:00 2001 From: womensrights Date: Tue, 2 May 2023 09:42:21 +0200 Subject: [PATCH 01/11] Create path-unwinding-requirements.md --- .../path-unwinding-requirements.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/requirements/path-unwinding-requirements.md diff --git a/docs/requirements/path-unwinding-requirements.md b/docs/requirements/path-unwinding-requirements.md new file mode 100644 index 00000000000..d62549d19d6 --- /dev/null +++ b/docs/requirements/path-unwinding-requirements.md @@ -0,0 +1,88 @@ + + +# Business requirements + +The implementation of fungible token path unwinding vastly simplifies token transfers for end users. End users are unlikely to understand ibc denominations in great detail, and the consequences a direct transfer from chain A, to chain B can have on the fungibility of a token at the destination chain B, when the token sent is not a native or originating token from chain A, and is native to another chain, e.g. chain C. + +Path Unwinding reduces the complexity of token transfer for the end user; a user simply needs to choose the final destination for their tokens and the complexity of determining the optimal route is abstracted away. This is a huge user experience improvement. + + +## Problem + + + +A fungible token A transferred from chain A to chain B is an ibc denomination at chain B, where the ibc denom trace records the path the token has travelled to reach its destination chain. + + + +A user now wants to send this ibc denomination of token A, originating from chain A, onto another chain, chain C. If a user transfers token A on chain B directly to chain C, it will not be fungible with token A sent directly from chain A to chain B. This is because the ibc denomination of token A on chain C is different in both cases due to token A travelling along different paths to reach the same destination. This is the most simple case of the problem involving only 3 chains. + +However, this problem is prevalent within the ecosystem and there are cases of ibc denominations on chains with >2 hops in the path. + + + +## Objectives + +To enable end users to automatically and atomically unwind fungible tokens when they specify a destination chain, so that tokens arrive at the destination chain with only 1 hop in the path. + + + +## Scope + + + +| Features | Release | +| --------- | ------- | +| Automatic and atomic path unwinding for fungible tokens suitable for end users initiating a transfer | v7.3.0 | + +# User requirements + +## Use cases + +### 1. Moving non-native assets between DeFi opportunities on different chains + +Users transfer tokens from an origin chain to a DeFi chain to benefit from yield opportunities or other use cases on that chain, different from the origin chain. A better yield opportunity could then arise and a user would want to move the tokens to another chain to take advantage of this opportunity. Rather than having to manually route the tokens back through the originating chain onto the new chain, it would be much simpler if they could only be concerned with the final destination they want the tokens to arrive at. + +For example, ATOM is native to the Cosmos Hub, a user could transfer ATOM to Osmosis and deposit in a liquidity pool to earn yield on this token. After depositing their ATOM into a pool on Osmosis, a better yield opportunity could arise, for example a better pool APY on another Cosmos DEX, e.g. Crescent or a better yield on lending ATOM on Umee. The user would then want to transfer the ATOM from Osmosis to Crescent (or Umee). + +### 2. Transferring liquid staking derivatives + +Liquid staking derivatives are minted on liquid staking zones and represent a staked asset. There is a common misconception from users that these derivatives originate on the chain of the original staked token. This results in users sending derivatives back to the chain of the natively staked token and then onto the next destination. + +For examples, a user has stATOM on Osmosis, they want to move the stATOM to Evmos, instead of going from Osmosis --> Stride --> Evmos, a user tries to unwind themself and routes the tokens Osmosis --> Cosmos Hub --> Evmos + +### 3. Moving a token that originated from an interoperability zone or chain, or asset issuer + +Tokens that originate from other blockchain ecosystems that don't yet support IBC, flow into the Cosmos ecosystem through interoperability zones. These tokens are then sent onto other chains with a specific use case for these tokens and a user could want to move this token from one chain to another. + +For example, ETH from Ethereum flows into Osmosis via Axelar, where the final step moving ETH from Ethereum to Osmosis uses an ICS-20 transfer from Axelar to Osmosis. A user may then want to move ETH from Osmosis onto another chain, for example Injective. However, the path with 1 hop would be a transfer from Axelar to Injective + + + + +# Functional requirements + + + +## Assumptions and dependencies + +1. A functional relayer implementation is required for this feature +2. There must be an on-chain registry on source chains that want to use path unwinding which contains information about possible ibc paths from this chain. As a minimum, information for all channels with `portID` relevant for ICS-20 and the `chainID` and `channelID` of connections from the chain. This is to enable routing of the final hop, from source to final destination without relying on an off-chain configuration. +3. The feature will have no impact on the existing function of a typical ICS-20 transfer where a native token is sent to another chain +4. Fees will be treated the same as with other IBC applications + + + + +## Features + +| ID | Description | Verification | Status | +| -- | ----------- | ------------ | ------ | + +# External interface requirements + + + +# Non-functional requirements + + \ No newline at end of file From 1484c6e1e837af056152af57661b0231c43b56a3 Mon Sep 17 00:00:00 2001 From: womensrights Date: Wed, 20 Mar 2024 09:41:00 +0100 Subject: [PATCH 02/11] Unwinding forwarding requirements --- ...ath-unwinding-forwarding -requirements.md} | 45 ++++++++++++++++--- 1 file changed, 39 insertions(+), 6 deletions(-) rename docs/requirements/{path-unwinding-requirements.md => path-unwinding-forwarding -requirements.md} (62%) diff --git a/docs/requirements/path-unwinding-requirements.md b/docs/requirements/path-unwinding-forwarding -requirements.md similarity index 62% rename from docs/requirements/path-unwinding-requirements.md rename to docs/requirements/path-unwinding-forwarding -requirements.md index d62549d19d6..cf01fdc4e08 100644 --- a/docs/requirements/path-unwinding-requirements.md +++ b/docs/requirements/path-unwinding-forwarding -requirements.md @@ -4,7 +4,9 @@ The implementation of fungible token path unwinding vastly simplifies token transfers for end users. End users are unlikely to understand ibc denominations in great detail, and the consequences a direct transfer from chain A, to chain B can have on the fungibility of a token at the destination chain B, when the token sent is not a native or originating token from chain A, and is native to another chain, e.g. chain C. -Path Unwinding reduces the complexity of token transfer for the end user; a user simply needs to choose the final destination for their tokens and the complexity of determining the optimal route is abstracted away. This is a huge user experience improvement. +Path Unwinding reduces the complexity of token transfer for the end user; a user simply needs to choose the final destination for their tokens and the complexity of determining the optimal route is abstracted away. This is a huge user experience improvement. + +In addition to unwinding, when a user recieves their token on a destination chain, they then want to use the token in some way. By enabling token forwarding, a user can recieve a token, perform some action with that token, for example a swap, and then send the token onto another chain. We observe that the complexity of IBC is increasingly being abstracted away from end users and automating workflows such as transfer, swap and forward with a single signed transaction significantly enhances usability. ## Problem @@ -19,11 +21,13 @@ A user now wants to send this ibc denomination of token A, originating from chai However, this problem is prevalent within the ecosystem and there are cases of ibc denominations on chains with >2 hops in the path. +Regarding forwarding, if a user wants to transfer tokens between chains, then perform an action with those tokens, without forwarding, a user would have to sign each transactions on every chain and wait for the tokens to arrive at the destination before performing the next action. This is time consuming and a provides a poor user experience, a user also cannot just specify the desired outcome of their workflow in a trivial way. + ## Objectives -To enable end users to automatically and atomically unwind fungible tokens when they specify a destination chain, so that tokens arrive at the destination chain with only 1 hop in the path. +To enable end users to automatically and atomically unwind fungible tokens when they specify a destination chain, so that tokens arrive at the destination chain with only 1 hop in the path and to be able to forward the token to another destination after it has been unwound. @@ -33,7 +37,8 @@ To enable end users to automatically and atomically unwind fungible tokens when | Features | Release | | --------- | ------- | -| Automatic and atomic path unwinding for fungible tokens suitable for end users initiating a transfer | v7.3.0 | +| Automatic and atomic path unwinding for fungible tokens suitable for end users initiating a transfer | v9.0.0 | +| Token forwarding for fungible tokens for end users initiating a transfer | v9.0.0 | # User requirements @@ -57,8 +62,10 @@ Tokens that originate from other blockchain ecosystems that don't yet support IB For example, ETH from Ethereum flows into Osmosis via Axelar, where the final step moving ETH from Ethereum to Osmosis uses an ICS-20 transfer from Axelar to Osmosis. A user may then want to move ETH from Osmosis onto another chain, for example Injective. However, the path with 1 hop would be a transfer from Axelar to Injective +### 4. Moving a token from one chain to another, swapping the token and transferring it onwards to a new destination + +A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wants to instead have AKT on Akash. The user must transfer to ATOM to a DEX chain, swap the ATOM for AKT and then send the AKT onwards to Akash. - # Functional requirements @@ -67,9 +74,11 @@ For example, ETH from Ethereum flows into Osmosis via Axelar, where the final st ## Assumptions and dependencies 1. A functional relayer implementation is required for this feature -2. There must be an on-chain registry on source chains that want to use path unwinding which contains information about possible ibc paths from this chain. As a minimum, information for all channels with `portID` relevant for ICS-20 and the `chainID` and `channelID` of connections from the chain. This is to enable routing of the final hop, from source to final destination without relying on an off-chain configuration. +2. Routing information for the final hop for unwinding or for forwarding is configured for the user through a front end client, or configured by another means using off-chain data. 3. The feature will have no impact on the existing function of a typical ICS-20 transfer where a native token is sent to another chain 4. Fees will be treated the same as with other IBC applications +5. The functionality to enable a specific action before forwarding is not in scope of these requirements +6. If a transfer contains multiple unique tokens, the unwinding functionality only needs to support a single denom, i.e. if there is a transfer containing a native token and 1 hop denom being sent from source to destination, unwinding should support unwinding the 1 hop denom and sending the native token directly to the destination. Support for transfer and unwind for native token and 2+ 1 hop denoms is not required. @@ -77,12 +86,36 @@ For example, ETH from Ethereum flows into Osmosis via Axelar, where the final st ## Features | ID | Description | Verification | Status | -| -- | ----------- | ------------ | ------ | +| -- | ------ | ------------ | ------ | +| -- | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a default | ------------ | draft | +| -- | If a user does not want to unwind the tokens, then they can override the default unwinding | ------------ | draft | +| -- | The unwinding shall completely succeed or the tokens are recoverable on the chain they were sent from by the user | ------------ | draft | +| -- | When unwinding is used in combination with forwarding, both the unwind and forwarding should succeed or the tokens should be recoverable on the sending chain | ------------ | draft | +| -- | The forwarding mechanism shall allow a user to transfer tokens beyond the first destination for those tokens | ------------ | draft | +| -- | The forwarding mechanism shall allow tokens to have some action performed on them before being sent onto a new destination | ------------ | draft | +| -- | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | ------------ | draft | +| -- | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | ------------ | draft | + -- | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | ------------ | draft | + | -- | When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | ------------ | draft | + # External interface requirements +| ID | Description | Verification | Status | +| -- | ----------- | ------------ | ------ | +| -- | There must be a CLI interface to initiate a transfer using path unwinding | ------------ | draft | +| -- | There must be a CLI interface to initiate a transfer using forwarding | ------------ | draft | +| -- | There must be a CLI interface to initiate a transfer using unwinding and forwarding in combination | ------------ | draft | + # Non-functional requirements +### Security + +| ID | Description | Verification | Status | +| -- | ----------- | ------------ | ------ | +| -- | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | ------------ | draft | + + \ No newline at end of file From f7fd1612472e32dcf19d31a3c89559b9c56a7c3c Mon Sep 17 00:00:00 2001 From: womensrights Date: Wed, 20 Mar 2024 09:44:38 +0100 Subject: [PATCH 03/11] Update path-unwinding-forwarding -requirements.md --- ...path-unwinding-forwarding -requirements.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/requirements/path-unwinding-forwarding -requirements.md b/docs/requirements/path-unwinding-forwarding -requirements.md index cf01fdc4e08..92bd291d740 100644 --- a/docs/requirements/path-unwinding-forwarding -requirements.md +++ b/docs/requirements/path-unwinding-forwarding -requirements.md @@ -87,16 +87,16 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa | ID | Description | Verification | Status | | -- | ------ | ------------ | ------ | -| -- | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a default | ------------ | draft | -| -- | If a user does not want to unwind the tokens, then they can override the default unwinding | ------------ | draft | -| -- | The unwinding shall completely succeed or the tokens are recoverable on the chain they were sent from by the user | ------------ | draft | -| -- | When unwinding is used in combination with forwarding, both the unwind and forwarding should succeed or the tokens should be recoverable on the sending chain | ------------ | draft | -| -- | The forwarding mechanism shall allow a user to transfer tokens beyond the first destination for those tokens | ------------ | draft | -| -- | The forwarding mechanism shall allow tokens to have some action performed on them before being sent onto a new destination | ------------ | draft | -| -- | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | ------------ | draft | -| -- | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | ------------ | draft | - -- | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | ------------ | draft | - | -- | When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | ------------ | draft | +| 1.01 | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a default | ------------ | draft | +| 1.02 | If a user does not want to unwind the tokens, then they can override the default unwinding | ------------ | draft | +| 1.03 | The unwinding shall completely succeed or the tokens are recoverable on the chain they were sent from by the user | ------------ | draft | +| 1.04 | When unwinding is used in combination with forwarding, both the unwind and forwarding should succeed or the tokens should be recoverable on the sending chain | ------------ | draft | +| 1.05 | The forwarding mechanism shall allow a user to transfer tokens beyond the first destination for those tokens | ------------ | draft | +| 1.06 | The forwarding mechanism shall allow tokens to have some action performed on them before being sent onto a new destination | ------------ | draft | +| 1.07 | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | ------------ | draft | +| 1.08 | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | ------------ | draft | + 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | ------------ | draft | + | 1.10| When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | ------------ | draft | # External interface requirements @@ -105,9 +105,9 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa | ID | Description | Verification | Status | | -- | ----------- | ------------ | ------ | -| -- | There must be a CLI interface to initiate a transfer using path unwinding | ------------ | draft | -| -- | There must be a CLI interface to initiate a transfer using forwarding | ------------ | draft | -| -- | There must be a CLI interface to initiate a transfer using unwinding and forwarding in combination | ------------ | draft | +| 2.01 | There must be a CLI interface to initiate a transfer using path unwinding | ------------ | draft | +| 2.02 | There must be a CLI interface to initiate a transfer using forwarding | ------------ | draft | +| 2.03 | There must be a CLI interface to initiate a transfer using unwinding and forwarding in combination | ------------ | draft | # Non-functional requirements @@ -115,7 +115,7 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa | ID | Description | Verification | Status | | -- | ----------- | ------------ | ------ | -| -- | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | ------------ | draft | +| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | ------------ | draft | \ No newline at end of file From b741e49ed24d3737a986e7709f2263084aa6ed28 Mon Sep 17 00:00:00 2001 From: womensrights Date: Wed, 20 Mar 2024 13:47:37 +0100 Subject: [PATCH 04/11] fix linter and remove commented guide --- ...path-unwinding-forwarding -requirements.md | 31 +++---------------- 1 file changed, 4 insertions(+), 27 deletions(-) diff --git a/docs/requirements/path-unwinding-forwarding -requirements.md b/docs/requirements/path-unwinding-forwarding -requirements.md index 92bd291d740..1e931058a02 100644 --- a/docs/requirements/path-unwinding-forwarding -requirements.md +++ b/docs/requirements/path-unwinding-forwarding -requirements.md @@ -8,33 +8,22 @@ Path Unwinding reduces the complexity of token transfer for the end user; a user In addition to unwinding, when a user recieves their token on a destination chain, they then want to use the token in some way. By enabling token forwarding, a user can recieve a token, perform some action with that token, for example a swap, and then send the token onto another chain. We observe that the complexity of IBC is increasingly being abstracted away from end users and automating workflows such as transfer, swap and forward with a single signed transaction significantly enhances usability. - ## Problem - - A fungible token A transferred from chain A to chain B is an ibc denomination at chain B, where the ibc denom trace records the path the token has travelled to reach its destination chain. - - A user now wants to send this ibc denomination of token A, originating from chain A, onto another chain, chain C. If a user transfers token A on chain B directly to chain C, it will not be fungible with token A sent directly from chain A to chain B. This is because the ibc denomination of token A on chain C is different in both cases due to token A travelling along different paths to reach the same destination. This is the most simple case of the problem involving only 3 chains. However, this problem is prevalent within the ecosystem and there are cases of ibc denominations on chains with >2 hops in the path. Regarding forwarding, if a user wants to transfer tokens between chains, then perform an action with those tokens, without forwarding, a user would have to sign each transactions on every chain and wait for the tokens to arrive at the destination before performing the next action. This is time consuming and a provides a poor user experience, a user also cannot just specify the desired outcome of their workflow in a trivial way. - - ## Objectives To enable end users to automatically and atomically unwind fungible tokens when they specify a destination chain, so that tokens arrive at the destination chain with only 1 hop in the path and to be able to forward the token to another destination after it has been unwound. - - ## Scope - - | Features | Release | | --------- | ------- | | Automatic and atomic path unwinding for fungible tokens suitable for end users initiating a transfer | v9.0.0 | @@ -66,11 +55,8 @@ For example, ETH from Ethereum flows into Osmosis via Axelar, where the final st A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wants to instead have AKT on Akash. The user must transfer to ATOM to a DEX chain, swap the ATOM for AKT and then send the AKT onwards to Akash. - # Functional requirements - - ## Assumptions and dependencies 1. A functional relayer implementation is required for this feature @@ -80,9 +66,6 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa 5. The functionality to enable a specific action before forwarding is not in scope of these requirements 6. If a transfer contains multiple unique tokens, the unwinding functionality only needs to support a single denom, i.e. if there is a transfer containing a native token and 1 hop denom being sent from source to destination, unwinding should support unwinding the 1 hop denom and sending the native token directly to the destination. Support for transfer and unwind for native token and 2+ 1 hop denoms is not required. - - - ## Features | ID | Description | Verification | Status | @@ -95,14 +78,11 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa | 1.06 | The forwarding mechanism shall allow tokens to have some action performed on them before being sent onto a new destination | ------------ | draft | | 1.07 | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | ------------ | draft | | 1.08 | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | ------------ | draft | - 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | ------------ | draft | - | 1.10| When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | ------------ | draft | - + | 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | ------------ | draft | + | 1.10| When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | ------------ | draft | # External interface requirements - - | ID | Description | Verification | Status | | -- | ----------- | ------------ | ------ | | 2.01 | There must be a CLI interface to initiate a transfer using path unwinding | ------------ | draft | @@ -111,11 +91,8 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa # Non-functional requirements -### Security +## Security | ID | Description | Verification | Status | | -- | ----------- | ------------ | ------ | -| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | ------------ | draft | - - - \ No newline at end of file +| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | ------------ | draft | \ No newline at end of file From 92761868f03f8ea0a98ab0aa78152935ab5d5774 Mon Sep 17 00:00:00 2001 From: womensrights Date: Wed, 20 Mar 2024 13:49:56 +0100 Subject: [PATCH 05/11] fix eof violation --- docs/requirements/path-unwinding-forwarding -requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements/path-unwinding-forwarding -requirements.md b/docs/requirements/path-unwinding-forwarding -requirements.md index 1e931058a02..aeaa156b97b 100644 --- a/docs/requirements/path-unwinding-forwarding -requirements.md +++ b/docs/requirements/path-unwinding-forwarding -requirements.md @@ -95,4 +95,4 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa | ID | Description | Verification | Status | | -- | ----------- | ------------ | ------ | -| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | ------------ | draft | \ No newline at end of file +| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | ------------ | draft | From 50e46635d9b277751c5cf4808043ff112e39ce8c Mon Sep 17 00:00:00 2001 From: Carlos Rodriguez Date: Wed, 17 Apr 2024 10:47:43 +0200 Subject: [PATCH 06/11] formatting nits --- ...path-unwinding-forwarding -requirements.md | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/requirements/path-unwinding-forwarding -requirements.md b/docs/requirements/path-unwinding-forwarding -requirements.md index aeaa156b97b..936e494bdfe 100644 --- a/docs/requirements/path-unwinding-forwarding -requirements.md +++ b/docs/requirements/path-unwinding-forwarding -requirements.md @@ -2,21 +2,21 @@ # Business requirements -The implementation of fungible token path unwinding vastly simplifies token transfers for end users. End users are unlikely to understand ibc denominations in great detail, and the consequences a direct transfer from chain A, to chain B can have on the fungibility of a token at the destination chain B, when the token sent is not a native or originating token from chain A, and is native to another chain, e.g. chain C. +The implementation of fungible token path unwinding vastly simplifies token transfers for end users. End users are unlikely to understand IBC denominations in great detail, and the consequences a direct transfer from chain A, to chain B can have on the fungibility of a token at the destination chain B, when the token sent is not a native or originating token from chain A, and is native to another chain, e.g. chain C. -Path Unwinding reduces the complexity of token transfer for the end user; a user simply needs to choose the final destination for their tokens and the complexity of determining the optimal route is abstracted away. This is a huge user experience improvement. +Path unwinding reduces the complexity of token transfer for the end user; a user simply needs to choose the final destination for their tokens and the complexity of determining the optimal route is abstracted away. This is a huge user experience improvement. In addition to unwinding, when a user recieves their token on a destination chain, they then want to use the token in some way. By enabling token forwarding, a user can recieve a token, perform some action with that token, for example a swap, and then send the token onto another chain. We observe that the complexity of IBC is increasingly being abstracted away from end users and automating workflows such as transfer, swap and forward with a single signed transaction significantly enhances usability. ## Problem -A fungible token A transferred from chain A to chain B is an ibc denomination at chain B, where the ibc denom trace records the path the token has travelled to reach its destination chain. +A fungible token A transferred from chain A to chain B is an IBC denomination at chain B, where the IBC denom trace records the path the token has travelled to reach its destination chain. -A user now wants to send this ibc denomination of token A, originating from chain A, onto another chain, chain C. If a user transfers token A on chain B directly to chain C, it will not be fungible with token A sent directly from chain A to chain B. This is because the ibc denomination of token A on chain C is different in both cases due to token A travelling along different paths to reach the same destination. This is the most simple case of the problem involving only 3 chains. +A user now wants to send this IBC denomination of token A, originating from chain A, onto another chain, chain C. If a user transfers token A on chain B directly to chain C, it will not be fungible with token A sent directly from chain A to chain C. This is because the IBC denomination of token A on chain C is different in both cases due to token A travelling along different paths to reach the same destination. This is the most simple case of the problem involving only 3 chains. -However, this problem is prevalent within the ecosystem and there are cases of ibc denominations on chains with >2 hops in the path. +However, this problem is prevalent within the ecosystem and there are cases of IBC denominations on chains with >2 hops in the path. -Regarding forwarding, if a user wants to transfer tokens between chains, then perform an action with those tokens, without forwarding, a user would have to sign each transactions on every chain and wait for the tokens to arrive at the destination before performing the next action. This is time consuming and a provides a poor user experience, a user also cannot just specify the desired outcome of their workflow in a trivial way. +Regarding forwarding, if a user wants to transfer tokens between chains, then perform an action with those tokens, without forwarding, a user would have to sign each transaction on every chain and wait for the tokens to arrive at the destination before performing the next action. This is time consuming and a provides a poor user experience, a user also cannot just specify the desired outcome of their workflow in a trivial way. ## Objectives @@ -43,13 +43,13 @@ For example, ATOM is native to the Cosmos Hub, a user could transfer ATOM to Osm Liquid staking derivatives are minted on liquid staking zones and represent a staked asset. There is a common misconception from users that these derivatives originate on the chain of the original staked token. This results in users sending derivatives back to the chain of the natively staked token and then onto the next destination. -For examples, a user has stATOM on Osmosis, they want to move the stATOM to Evmos, instead of going from Osmosis --> Stride --> Evmos, a user tries to unwind themself and routes the tokens Osmosis --> Cosmos Hub --> Evmos +For examples, a user has stATOM on Osmosis, they want to move the stATOM to Evmos, instead of going from Osmosis --> Stride --> Evmos, a user tries to unwind themself and routes the tokens Osmosis --> Cosmos Hub --> Evmos. ### 3. Moving a token that originated from an interoperability zone or chain, or asset issuer Tokens that originate from other blockchain ecosystems that don't yet support IBC, flow into the Cosmos ecosystem through interoperability zones. These tokens are then sent onto other chains with a specific use case for these tokens and a user could want to move this token from one chain to another. -For example, ETH from Ethereum flows into Osmosis via Axelar, where the final step moving ETH from Ethereum to Osmosis uses an ICS-20 transfer from Axelar to Osmosis. A user may then want to move ETH from Osmosis onto another chain, for example Injective. However, the path with 1 hop would be a transfer from Axelar to Injective +For example, ETH from Ethereum flows into Osmosis via Axelar, where the final step moving ETH from Ethereum to Osmosis uses an ICS-20 transfer from Axelar to Osmosis. A user may then want to move ETH from Osmosis onto another chain, for example Injective. However, the path with 1 hop would be a transfer from Axelar to Injective. ### 4. Moving a token from one chain to another, swapping the token and transferring it onwards to a new destination @@ -59,35 +59,35 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa ## Assumptions and dependencies -1. A functional relayer implementation is required for this feature +1. A functional relayer implementation is required for this feature. 2. Routing information for the final hop for unwinding or for forwarding is configured for the user through a front end client, or configured by another means using off-chain data. -3. The feature will have no impact on the existing function of a typical ICS-20 transfer where a native token is sent to another chain -4. Fees will be treated the same as with other IBC applications -5. The functionality to enable a specific action before forwarding is not in scope of these requirements -6. If a transfer contains multiple unique tokens, the unwinding functionality only needs to support a single denom, i.e. if there is a transfer containing a native token and 1 hop denom being sent from source to destination, unwinding should support unwinding the 1 hop denom and sending the native token directly to the destination. Support for transfer and unwind for native token and 2+ 1 hop denoms is not required. +3. The feature will have no impact on the existing function of a typical ICS-20 transfer where a native token is sent to another chain. +4. Fees will be treated the same as with other IBC applications. +5. The functionality to enable a specific action before forwarding is not in scope of these requirements. +6. If a transfer contains multiple unique tokens, the unwinding functionality only needs to support a single denom, i.e. if there is a transfer containing a native token and 1 hop denom being sent from source to destination, unwinding should support unwinding the 1 hop denom and sending the native token directly to the destination. Support for transfer and unwind for native token and 2+ 1 hop denoms is not required. ## Features | ID | Description | Verification | Status | -| -- | ------ | ------------ | ------ | -| 1.01 | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a default | ------------ | draft | -| 1.02 | If a user does not want to unwind the tokens, then they can override the default unwinding | ------------ | draft | -| 1.03 | The unwinding shall completely succeed or the tokens are recoverable on the chain they were sent from by the user | ------------ | draft | -| 1.04 | When unwinding is used in combination with forwarding, both the unwind and forwarding should succeed or the tokens should be recoverable on the sending chain | ------------ | draft | -| 1.05 | The forwarding mechanism shall allow a user to transfer tokens beyond the first destination for those tokens | ------------ | draft | -| 1.06 | The forwarding mechanism shall allow tokens to have some action performed on them before being sent onto a new destination | ------------ | draft | -| 1.07 | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | ------------ | draft | -| 1.08 | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | ------------ | draft | - | 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | ------------ | draft | - | 1.10| When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | ------------ | draft | +| -- | ----------- | ------------ | ------ | +| 1.01 | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a default | | `Draft` | +| 1.02 | If a user does not want to unwind the tokens, then they can override the default unwinding | | `Draft` | +| 1.03 | The unwinding shall completely succeed or the tokens are recoverable on the chain they were sent from by the user | | `Draft` | +| 1.04 | When unwinding is used in combination with forwarding, both the unwind and forwarding should succeed or the tokens should be recoverable on the sending chain | | `Draft` | +| 1.05 | The forwarding mechanism shall allow a user to transfer tokens beyond the first destination for those tokens | | `Draft` | +| 1.06 | The forwarding mechanism shall allow tokens to have some action performed on them before being sent onto a new destination | | `Draft` | +| 1.07 | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | | `Draft` | +| 1.08 | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | | `Draft` | +| 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | | `Draft` | +| 1.10 | When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | | `Draft` | # External interface requirements | ID | Description | Verification | Status | | -- | ----------- | ------------ | ------ | -| 2.01 | There must be a CLI interface to initiate a transfer using path unwinding | ------------ | draft | -| 2.02 | There must be a CLI interface to initiate a transfer using forwarding | ------------ | draft | -| 2.03 | There must be a CLI interface to initiate a transfer using unwinding and forwarding in combination | ------------ | draft | +| 2.01 | There must be a CLI interface to initiate a transfer using path unwinding | | `Draft` | +| 2.02 | There must be a CLI interface to initiate a transfer using forwarding | | `Draft` | +| 2.03 | There must be a CLI interface to initiate a transfer using unwinding and forwarding in combination | | `Draft` | # Non-functional requirements @@ -95,4 +95,4 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa | ID | Description | Verification | Status | | -- | ----------- | ------------ | ------ | -| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | ------------ | draft | +| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | | `Draft` | From 354dcf39d9a0250b006afadf04fb131073ab540b Mon Sep 17 00:00:00 2001 From: womensrights Date: Mon, 10 Jun 2024 17:49:50 +0200 Subject: [PATCH 07/11] Update path-unwinding-forwarding -requirements.md --- ...path-unwinding-forwarding -requirements.md | 98 ------------------- 1 file changed, 98 deletions(-) delete mode 100644 docs/requirements/path-unwinding-forwarding -requirements.md diff --git a/docs/requirements/path-unwinding-forwarding -requirements.md b/docs/requirements/path-unwinding-forwarding -requirements.md deleted file mode 100644 index 936e494bdfe..00000000000 --- a/docs/requirements/path-unwinding-forwarding -requirements.md +++ /dev/null @@ -1,98 +0,0 @@ - - -# Business requirements - -The implementation of fungible token path unwinding vastly simplifies token transfers for end users. End users are unlikely to understand IBC denominations in great detail, and the consequences a direct transfer from chain A, to chain B can have on the fungibility of a token at the destination chain B, when the token sent is not a native or originating token from chain A, and is native to another chain, e.g. chain C. - -Path unwinding reduces the complexity of token transfer for the end user; a user simply needs to choose the final destination for their tokens and the complexity of determining the optimal route is abstracted away. This is a huge user experience improvement. - -In addition to unwinding, when a user recieves their token on a destination chain, they then want to use the token in some way. By enabling token forwarding, a user can recieve a token, perform some action with that token, for example a swap, and then send the token onto another chain. We observe that the complexity of IBC is increasingly being abstracted away from end users and automating workflows such as transfer, swap and forward with a single signed transaction significantly enhances usability. - -## Problem - -A fungible token A transferred from chain A to chain B is an IBC denomination at chain B, where the IBC denom trace records the path the token has travelled to reach its destination chain. - -A user now wants to send this IBC denomination of token A, originating from chain A, onto another chain, chain C. If a user transfers token A on chain B directly to chain C, it will not be fungible with token A sent directly from chain A to chain C. This is because the IBC denomination of token A on chain C is different in both cases due to token A travelling along different paths to reach the same destination. This is the most simple case of the problem involving only 3 chains. - -However, this problem is prevalent within the ecosystem and there are cases of IBC denominations on chains with >2 hops in the path. - -Regarding forwarding, if a user wants to transfer tokens between chains, then perform an action with those tokens, without forwarding, a user would have to sign each transaction on every chain and wait for the tokens to arrive at the destination before performing the next action. This is time consuming and a provides a poor user experience, a user also cannot just specify the desired outcome of their workflow in a trivial way. - -## Objectives - -To enable end users to automatically and atomically unwind fungible tokens when they specify a destination chain, so that tokens arrive at the destination chain with only 1 hop in the path and to be able to forward the token to another destination after it has been unwound. - -## Scope - -| Features | Release | -| --------- | ------- | -| Automatic and atomic path unwinding for fungible tokens suitable for end users initiating a transfer | v9.0.0 | -| Token forwarding for fungible tokens for end users initiating a transfer | v9.0.0 | - -# User requirements - -## Use cases - -### 1. Moving non-native assets between DeFi opportunities on different chains - -Users transfer tokens from an origin chain to a DeFi chain to benefit from yield opportunities or other use cases on that chain, different from the origin chain. A better yield opportunity could then arise and a user would want to move the tokens to another chain to take advantage of this opportunity. Rather than having to manually route the tokens back through the originating chain onto the new chain, it would be much simpler if they could only be concerned with the final destination they want the tokens to arrive at. - -For example, ATOM is native to the Cosmos Hub, a user could transfer ATOM to Osmosis and deposit in a liquidity pool to earn yield on this token. After depositing their ATOM into a pool on Osmosis, a better yield opportunity could arise, for example a better pool APY on another Cosmos DEX, e.g. Crescent or a better yield on lending ATOM on Umee. The user would then want to transfer the ATOM from Osmosis to Crescent (or Umee). - -### 2. Transferring liquid staking derivatives - -Liquid staking derivatives are minted on liquid staking zones and represent a staked asset. There is a common misconception from users that these derivatives originate on the chain of the original staked token. This results in users sending derivatives back to the chain of the natively staked token and then onto the next destination. - -For examples, a user has stATOM on Osmosis, they want to move the stATOM to Evmos, instead of going from Osmosis --> Stride --> Evmos, a user tries to unwind themself and routes the tokens Osmosis --> Cosmos Hub --> Evmos. - -### 3. Moving a token that originated from an interoperability zone or chain, or asset issuer - -Tokens that originate from other blockchain ecosystems that don't yet support IBC, flow into the Cosmos ecosystem through interoperability zones. These tokens are then sent onto other chains with a specific use case for these tokens and a user could want to move this token from one chain to another. - -For example, ETH from Ethereum flows into Osmosis via Axelar, where the final step moving ETH from Ethereum to Osmosis uses an ICS-20 transfer from Axelar to Osmosis. A user may then want to move ETH from Osmosis onto another chain, for example Injective. However, the path with 1 hop would be a transfer from Axelar to Injective. - -### 4. Moving a token from one chain to another, swapping the token and transferring it onwards to a new destination - -A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wants to instead have AKT on Akash. The user must transfer to ATOM to a DEX chain, swap the ATOM for AKT and then send the AKT onwards to Akash. - -# Functional requirements - -## Assumptions and dependencies - -1. A functional relayer implementation is required for this feature. -2. Routing information for the final hop for unwinding or for forwarding is configured for the user through a front end client, or configured by another means using off-chain data. -3. The feature will have no impact on the existing function of a typical ICS-20 transfer where a native token is sent to another chain. -4. Fees will be treated the same as with other IBC applications. -5. The functionality to enable a specific action before forwarding is not in scope of these requirements. -6. If a transfer contains multiple unique tokens, the unwinding functionality only needs to support a single denom, i.e. if there is a transfer containing a native token and 1 hop denom being sent from source to destination, unwinding should support unwinding the 1 hop denom and sending the native token directly to the destination. Support for transfer and unwind for native token and 2+ 1 hop denoms is not required. - -## Features - -| ID | Description | Verification | Status | -| -- | ----------- | ------------ | ------ | -| 1.01 | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a default | | `Draft` | -| 1.02 | If a user does not want to unwind the tokens, then they can override the default unwinding | | `Draft` | -| 1.03 | The unwinding shall completely succeed or the tokens are recoverable on the chain they were sent from by the user | | `Draft` | -| 1.04 | When unwinding is used in combination with forwarding, both the unwind and forwarding should succeed or the tokens should be recoverable on the sending chain | | `Draft` | -| 1.05 | The forwarding mechanism shall allow a user to transfer tokens beyond the first destination for those tokens | | `Draft` | -| 1.06 | The forwarding mechanism shall allow tokens to have some action performed on them before being sent onto a new destination | | `Draft` | -| 1.07 | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | | `Draft` | -| 1.08 | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | | `Draft` | -| 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | | `Draft` | -| 1.10 | When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | | `Draft` | - -# External interface requirements - -| ID | Description | Verification | Status | -| -- | ----------- | ------------ | ------ | -| 2.01 | There must be a CLI interface to initiate a transfer using path unwinding | | `Draft` | -| 2.02 | There must be a CLI interface to initiate a transfer using forwarding | | `Draft` | -| 2.03 | There must be a CLI interface to initiate a transfer using unwinding and forwarding in combination | | `Draft` | - -# Non-functional requirements - -## Security - -| ID | Description | Verification | Status | -| -- | ----------- | ------------ | ------ | -| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | | `Draft` | From d75035f3ac50eed12dc6589a74063552b96cb058 Mon Sep 17 00:00:00 2001 From: womensrights Date: Mon, 10 Jun 2024 17:50:57 +0200 Subject: [PATCH 08/11] Create path-unwinding-forwarding-requirements.md --- .../path-unwinding-forwarding-requirements.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/requirements/path-unwinding-forwarding-requirements.md diff --git a/docs/requirements/path-unwinding-forwarding-requirements.md b/docs/requirements/path-unwinding-forwarding-requirements.md new file mode 100644 index 00000000000..796c018242a --- /dev/null +++ b/docs/requirements/path-unwinding-forwarding-requirements.md @@ -0,0 +1,99 @@ + + +# Business requirements + +The implementation of fungible token path unwinding vastly simplifies token transfers for end users. End users are unlikely to understand IBC denominations in great detail, and the consequences a direct transfer from chain A, to chain B can have on the fungibility of a token at the destination chain B, when the token sent is not a native or originating token from chain A, and is native to another chain, e.g. chain C. + +Path unwinding reduces the complexity of token transfer for the end user; a user simply needs to choose the final destination for their tokens and the complexity of determining the optimal route is abstracted away. This is a huge user experience improvement. + +In addition to unwinding, when a user recieves their token on a destination chain, they then want to use the token in some way. By enabling token forwarding, a user can recieve a token, perform some action with that token, for example a swap, and then send the token onto another chain. We observe that the complexity of IBC is increasingly being abstracted away from end users and automating workflows such as transfer, swap and forward with a single signed transaction significantly enhances usability. + +## Problem + +A fungible token A transferred from chain A to chain B is an IBC denomination at chain B, where the IBC denom trace records the path the token has travelled to reach its destination chain. + +A user now wants to send this IBC denomination of token A, originating from chain A, onto another chain, chain C. If a user transfers token A on chain B directly to chain C, it will not be fungible with token A sent directly from chain A to chain C. This is because the IBC denomination of token A on chain C is different in both cases due to token A travelling along different paths to reach the same destination. This is the most simple case of the problem involving only 3 chains. + +However, this problem is prevalent within the ecosystem and there are cases of IBC denominations on chains with >2 hops in the path. + +Regarding forwarding, if a user wants to transfer tokens between chains, then perform an action with those tokens, without forwarding, a user would have to sign each transaction on every chain and wait for the tokens to arrive at the destination before performing the next action. This is time consuming and a provides a poor user experience, a user also cannot just specify the desired outcome of their workflow in a trivial way. + +## Objectives + +To enable end users to automatically and atomically unwind fungible tokens when they specify a destination chain, so that tokens arrive at the destination chain with only 1 hop in the path and to be able to forward the token to another destination after it has been unwound. + +## Scope + +| Features | Release | +| --------- | ------- | +| Automatic and atomic path unwinding for fungible tokens suitable for end users initiating a transfer | v9.0.0 | +| Token forwarding for fungible tokens for end users initiating a transfer | v9.0.0 | + +# User requirements + +## Use cases + +### 1. Moving non-native assets between DeFi opportunities on different chains + +Users transfer tokens from an origin chain to a DeFi chain to benefit from yield opportunities or other use cases on that chain, different from the origin chain. A better yield opportunity could then arise and a user would want to move the tokens to another chain to take advantage of this opportunity. Rather than having to manually route the tokens back through the originating chain onto the new chain, it would be much simpler if they could only be concerned with the final destination they want the tokens to arrive at. + +For example, ATOM is native to the Cosmos Hub, a user could transfer ATOM to Osmosis and deposit in a liquidity pool to earn yield on this token. After depositing their ATOM into a pool on Osmosis, a better yield opportunity could arise, for example a better pool APY on another Cosmos DEX, e.g. Crescent or a better yield on lending ATOM on Umee. The user would then want to transfer the ATOM from Osmosis to Crescent (or Umee). + +### 2. Transferring liquid staking derivatives + +Liquid staking derivatives are minted on liquid staking zones and represent a staked asset. There is a common misconception from users that these derivatives originate on the chain of the original staked token. This results in users sending derivatives back to the chain of the natively staked token and then onto the next destination. + +For examples, a user has stATOM on Osmosis, they want to move the stATOM to Evmos, instead of going from Osmosis --> Stride --> Evmos, a user tries to unwind themself and routes the tokens Osmosis --> Cosmos Hub --> Evmos. + +### 3. Moving a token that originated from an interoperability zone or chain, or asset issuer + +Tokens that originate from other blockchain ecosystems that don't yet support IBC, flow into the Cosmos ecosystem through interoperability zones. These tokens are then sent onto other chains with a specific use case for these tokens and a user could want to move this token from one chain to another. + +For example, ETH from Ethereum flows into Osmosis via Axelar, where the final step moving ETH from Ethereum to Osmosis uses an ICS-20 transfer from Axelar to Osmosis. A user may then want to move ETH from Osmosis onto another chain, for example Injective. However, the path with 1 hop would be a transfer from Axelar to Injective. + +### 4. Moving a token from one chain to another, swapping the token and transferring it onwards to a new destination + +A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wants to instead have AKT on Akash. The user must transfer to ATOM to a DEX chain, swap the ATOM for AKT and then send the AKT onwards to Akash. + +# Functional requirements + +## Assumptions and dependencies + +1. A functional relayer implementation is required for this feature. +2. Routing information for the final hop for unwinding or for forwarding is configured for the user through a front end client, or configured by another means using off-chain data. +3. The feature will have no impact on the existing function of a typical ICS-20 transfer where a native token is sent to another chain. +4. Fees will be treated the same as with other IBC applications. +5. The functionality to enable a specific action before forwarding is not in scope of these requirements. +6. If a transfer contains multiple unique tokens, the unwinding functionality only needs to support forwarding through the same path, i.e. if there is a transfer containing a native token and 1 hop denom being sent from source to destination, both tokens would unwind through the same path. In the future, it may be desirable for different tokens to be unwound through different paths, to support actions such as atomic transfer and supply liquidity to a liquidity pool, but it is currently out of scope for the first version of this feature. + +## Features + +| ID | Description | Verification | Status | +| -- | ----------- | ------------ | ------ | +| 1.01 | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a default | | `Draft` | +| 1.02 | If a user does not want to unwind the tokens, then they can override the default unwinding | | `Draft` | +| 1.03 | The unwinding shall completely succeed or the tokens are recoverable on the chain they were sent from by the user | | `Draft` | +| 1.04 | When unwinding is used in combination with forwarding, both the unwind and forwarding should succeed or the tokens should be recoverable on the sending chain | | `Draft` | +| 1.05 | The forwarding mechanism shall allow a user to transfer tokens beyond the first destination for those tokens | | `Draft` | +| 1.06 | The forwarding mechanism shall allow tokens to have some action performed on them before being sent onto a new destination | | `Draft` | +| 1.07 | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | | `Draft` | +| 1.08 | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | | `Draft` | +| 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | | `Draft` | +| 1.10 | When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | | `Draft` | +| 1.11 | When using unwinding in combination with x/authz, a granter can specify the allowed forwarding paths | | `Draft` | + +# External interface requirements + +| ID | Description | Verification | Status | +| -- | ----------- | ------------ | ------ | +| 2.01 | There must be a CLI interface to initiate a transfer using path unwinding | | `Draft` | +| 2.02 | There must be a CLI interface to initiate a transfer using forwarding | | `Draft` | +| 2.03 | There must be a CLI interface to initiate a transfer using unwinding and forwarding in combination | | `Draft` | + +# Non-functional requirements + +## Security + +| ID | Description | Verification | Status | +| -- | ----------- | ------------ | ------ | +| 3.01 | It must not be possible for a users tokens to be intercepted by another actor during path-unwinding or token forwarding | | `Draft` | From ee66e4c3503b7996cb9eb59bf20507712fd00d4a Mon Sep 17 00:00:00 2001 From: womensrights Date: Mon, 17 Jun 2024 18:44:22 +0200 Subject: [PATCH 09/11] Update path-unwinding-forwarding-requirements.md --- docs/requirements/path-unwinding-forwarding-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements/path-unwinding-forwarding-requirements.md b/docs/requirements/path-unwinding-forwarding-requirements.md index 796c018242a..f30d40e6ea1 100644 --- a/docs/requirements/path-unwinding-forwarding-requirements.md +++ b/docs/requirements/path-unwinding-forwarding-requirements.md @@ -79,7 +79,7 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa | 1.07 | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | | `Draft` | | 1.08 | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | | `Draft` | | 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | | `Draft` | -| 1.10 | When unwinding, it should be possible for the unwind route to the tokens origin to be introspected from the denomination trace | | `Draft` | +| 1.10 | When unwinding, it should be possible for the unwind route to reach the tokens origin to be introspected and input from the denomination trace or to be manually input by the user| | `Draft` | | 1.11 | When using unwinding in combination with x/authz, a granter can specify the allowed forwarding paths | | `Draft` | # External interface requirements From e85f6b72814047240e4de2ec18672b273b018227 Mon Sep 17 00:00:00 2001 From: womensrights Date: Mon, 15 Jul 2024 14:26:00 +0200 Subject: [PATCH 10/11] Update path-unwinding-forwarding-requirements.md --- .../path-unwinding-forwarding-requirements.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/requirements/path-unwinding-forwarding-requirements.md b/docs/requirements/path-unwinding-forwarding-requirements.md index f30d40e6ea1..94583056d60 100644 --- a/docs/requirements/path-unwinding-forwarding-requirements.md +++ b/docs/requirements/path-unwinding-forwarding-requirements.md @@ -62,16 +62,16 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa 1. A functional relayer implementation is required for this feature. 2. Routing information for the final hop for unwinding or for forwarding is configured for the user through a front end client, or configured by another means using off-chain data. 3. The feature will have no impact on the existing function of a typical ICS-20 transfer where a native token is sent to another chain. -4. Fees will be treated the same as with other IBC applications. +4. Fees are not within the scope of these requirements. 5. The functionality to enable a specific action before forwarding is not in scope of these requirements. -6. If a transfer contains multiple unique tokens, the unwinding functionality only needs to support forwarding through the same path, i.e. if there is a transfer containing a native token and 1 hop denom being sent from source to destination, both tokens would unwind through the same path. In the future, it may be desirable for different tokens to be unwound through different paths, to support actions such as atomic transfer and supply liquidity to a liquidity pool, but it is currently out of scope for the first version of this feature. +6. If a transfer contains multiple unique tokens, the unwinding and forwarding functionalities only need to support unwinding or forwarding through the same path, i.e. if there is a transfer containing a native token and 1 hop denom being sent from source to destination, both tokens would always go through the same path. In the future, it may be desirable for different tokens to be unwound through different paths, to support actions such as atomic transfer and supply liquidity to a liquidity pool, but it is currently out of scope for the first version of this feature. ## Features | ID | Description | Verification | Status | | -- | ----------- | ------------ | ------ | -| 1.01 | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a default | | `Draft` | -| 1.02 | If a user does not want to unwind the tokens, then they can override the default unwinding | | `Draft` | +| 1.01 | When a user initiates a transfer to a destination chain with an IBC denom with > 1 hop, the token shall be sent back to its originating chain before being sent onto the destination as a user selected option | | `Draft` | +| 1.02 | If a user wants to unwind tokens, then they can select this as option for the transfer | | `Draft` | | 1.03 | The unwinding shall completely succeed or the tokens are recoverable on the chain they were sent from by the user | | `Draft` | | 1.04 | When unwinding is used in combination with forwarding, both the unwind and forwarding should succeed or the tokens should be recoverable on the sending chain | | `Draft` | | 1.05 | The forwarding mechanism shall allow a user to transfer tokens beyond the first destination for those tokens | | `Draft` | From 3954e37672cfb8851e062cab6f915b0b4b0aa2e5 Mon Sep 17 00:00:00 2001 From: Susannah Evans <65018876+womensrights@users.noreply.github.com> Date: Wed, 7 Aug 2024 17:12:17 +0200 Subject: [PATCH 11/11] Update docs/requirements/path-unwinding-forwarding-requirements.md Co-authored-by: Damian Nolan --- docs/requirements/path-unwinding-forwarding-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements/path-unwinding-forwarding-requirements.md b/docs/requirements/path-unwinding-forwarding-requirements.md index 94583056d60..1c0c7a447a7 100644 --- a/docs/requirements/path-unwinding-forwarding-requirements.md +++ b/docs/requirements/path-unwinding-forwarding-requirements.md @@ -79,7 +79,7 @@ A user on one chain, for example the Cosmos Hub holds an asset, e.g. ATOM and wa | 1.07 | The routing information for forwarding or to go from unwound token to destination must be input with the initial transfer | | `Draft` | | 1.08 | If an intermediate chain does not have the unwinding or forwarding functionality, the tokens must be recoverable on the sending chain | | `Draft` | | 1.09 | If unwinding or forwarding fails, then the reason for the failure should be returned in an error | | `Draft` | -| 1.10 | When unwinding, it should be possible for the unwind route to reach the tokens origin to be introspected and input from the denomination trace or to be manually input by the user| | `Draft` | +| 1.10 | When unwinding, it should be possible for the forwarding path to be evaluated implicitly from introspecting the denomination trace or to be explicitly input as forwarding hops by the user | | `Draft` | | 1.11 | When using unwinding in combination with x/authz, a granter can specify the allowed forwarding paths | | `Draft` | # External interface requirements