Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 330df58

Browse files
joshcolts18joshcolts18
committedMar 19, 2024
full migration
0 parents  commit 330df58

File tree

73 files changed

+8728
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

73 files changed

+8728
-0
lines changed
 

‎api-reference/allow-unsafe---preventing---handling-bad-execution.mdx

+131
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: "`allow_unsafe`: Preventing & Handling Bad Execution"
3+
---
4+
5+
## Introduction
6+
7+
**The`allow_unsafe` parameter in the requests to `/route` & `/msgs_direct` endpoints is designed to protect users from bad trade execution.**
8+
9+
This parameter indicates whether you want to allow the API to return and execute a route even when our routing engine forecasts low or unknown execution quality:
10+
11+
* `allow_unsafe=false` (default): The API will throw an error instead of returning a route when the routing engine forecasts bad execution quality (i.e. \> 10% `price_impact` or difference between USD value in and out) or when execution quality can't be determined.
12+
* `allow_unsafe=true`: The API will return a route for a trade even when the routing engine forecasts bad execution quality (i.e. \> 10% `price_impact` or difference between USD value in and out) or when execution quality can't be determined. In these cases, the API appends a `warning` to the response in a `warning` field
13+
14+
<Note>
15+
16+
**Make sure you understand execution/quote quality measurements first**
17+
18+
Before reading this doc, you should read our documentation on quote quality: [ Understanding Quote Quality Metrics](/docs/understanding-quote-quality-metrics). This provides basic background information about the different ways the API measures whether a route will likely give a user a bad execution price, namely the difference between the USD value of the input and the output & on-chain price impact.
19+
</Note>
20+
## `allow_unsafe=false` Behavior
21+
22+
When `allow_unsafe=false`, the endpoint throws an error when execution quality is low (as measured by price impact or estimated USD value lost) or when execution quality can't be determined (i.e. neither of these measurements are available).
23+
24+
Below, we provide examples of each case where the API returns an error when `allow_unsafe=false`:
25+
26+
* `price_impact > .10`(the swap will move the on-chain price by more than 10%)
27+
* `(usd_amount_in-usd_amount_out)/usd_amount_in)>.10` (greater than 10% of the value of the input is lost)
28+
* Neither of the above metrics can be computed
29+
30+
The price impact is greater than 10% (`BAD_PRICE_ERROR`):
31+
32+
```JSON
33+
{
34+
"code": 3,
35+
"message": "swap execution price in route deviates too far from market price. expected price impact: 98.6915%",
36+
"details": [
37+
{
38+
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
39+
"reason": "BAD_PRICE_ERROR",
40+
"domain": "skip.money",
41+
"metadata": {}
42+
}
43+
]
44+
}
45+
```
46+
47+
The user loses more than 10% of their USD value (`BAD_PRICE_ERROR`):
48+
49+
```json
50+
{
51+
"code": 3,
52+
"message": "difference in usd value of route input and output is too large. input usd value: 1000 output usd value: 600",
53+
"details": [
54+
{
55+
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
56+
"reason": "BAD_PRICE_ERROR",
57+
"domain": "skip.money",
58+
"metadata": {}
59+
}
60+
]
61+
}
62+
```
63+
64+
The `price_impact` and the estimated USD value difference cannot be calculated (`LOW_INFO_ERROR`)
65+
66+
```json
67+
{
68+
"code": 3,
69+
"message": "unable to determine route safety",
70+
"details": [
71+
{
72+
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
73+
"reason": "LOW_INFO_ERROR",
74+
"domain": "skip.money",
75+
"metadata": {}
76+
}
77+
]
78+
}
79+
```
80+
81+
## `allow_unsafe=true` Behavior
82+
83+
When `allow_unsafe=true`, the endpoints will still return routes even when the routing engine forecasts will have bad execution price (measured by price\_impact or estimated USD lost), but they will have a `warning` field appended to them.
84+
85+
The `warning` field is populated exactly when the endpoints would return an error if `allow_unsafe` were `false`, namely:
86+
87+
* `price_impact > .10`(the swap will move the on-chain price by more than 10%)
88+
* `(usd_amount_in-usd_amount_out)/usd_amount_in)>.10` (greater than 10% of the value of the input is lost)
89+
* Neither of the above metrics can be computed
90+
91+
Below, we provide examples of each case where the API returns a warning
92+
93+
The price impact is greater than 10% (`BAD_PRICE_WARNING`):
94+
95+
```JSON
96+
"warning": {
97+
"type": "BAD_PRICE_WARNING",
98+
"message": "swap execution price in route deviates too far from market price. expected price impact: 98.6826%"
99+
}
100+
```
101+
102+
More than 10% of the USD value of the input is lost in the swap (`BAD_PRICE_WARNING`):
103+
104+
```
105+
"warning": {
106+
"type": "BAD_PRICE_WARNING",
107+
"message": "difference in usd value of route input and output is too large. input usd value: 1000 output usd value: 600"
108+
}
109+
```
110+
111+
The `price_impact` and the estimated USD value difference cannot be calculated (`LOW_INFO_ERROR`)
112+
113+
```
114+
"warning": {
115+
"type": "LOW_INFO_WARNING",
116+
"message": "unable to determine route safety"
117+
}
118+
```
119+
120+
## Best Practices for Protecting Users
121+
122+
**Above all else, we recommend setting `allow_unsafe=false`**
123+
124+
In addition, we recommend reading our documentation around [safe API integrations](/docs/safe-swapping-how-to-protect-users-from-harming-themselves) to learn about UX/UI practices that can further help prevent users from performing trades they'll immediately regret.
125+
126+
<Check>
127+
128+
Want to help us get better? Have questions or feedback?
129+
130+
You can reach us easily at support@skip.money or in [our developer support channel on TG](https://t.me/+3y5biSyZRPIwZWIx)
131+
</Check>

‎api-reference/cross-chain-failure-cases.mdx

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: "Cross-chain Failure Cases"
3+
description: "This page covers the different ways our cross-chain swaps + transfers might fail to help identify failures and manage user expectations"
4+
---
5+
6+
## Failures during IBC Transfers and Swaps
7+
8+
There are two types of IBC failures that may occur when a user attempts to traverse a swap / transfer route produced by the Skip API.
9+
10+
1. **Pre-Swap / swap failures**
11+
* **What:** These are failures in the sequence of ICS-20 transfers leading up to the swap or a failure in the swap itself (usually due to slippage).
12+
* **Outcome / What to Expect:** The users' original source tokens are returned their starting address on the source chain
13+
* **Common failure sources:**
14+
* Inactive relayers on a channel allow a packet to timeout
15+
* Slippage (the amount out for the swap turns out to be less than the user's specified minimum, i.e. their slippage exceeds their tolerance)
16+
* The user / frontend provides an invalid recovery address
17+
* An IBC client on the destination chain has expired
18+
* **Examples:** Consider a route where the source asset is ATOM on Neutron, the destination asset is STRIDE on Stride, and the swap takes place on Osmosis:
19+
* The user's tokens transfer from Neutron to the Hub to Osmosis. The swap initiates but the price of STRIDE has gotten so high that the swap exceeds slippage tolerance and fails. A sequence of error acks is propagated back to the Hub then Neutron, releasing the user’s ATOM to their address on Neutron where they started
20+
* The user attempts to transfer tokens from Neutron to the hub, but the packet isn't picked up by a relayer for more than 5 minutes (past the timeout\_timestamp). When a relayer finally comes online, it relays a timeout message to Neutron, releasing the user's ATOM back to their address on Neutron where they first had it.
21+
* **For transfer-only routes:** This is the only kind of failure that may happen on a route that only contains transfers. Either the user's tokens will reach their destination chain as intended, or they will wind up with the same tokens, on the same chain where they started.
22+
23+
![In a pre-swap or swap related error, the user will end up with the same tokens they started with on their initial chain (e.g. ATOM on Neutron in this example)](/images/6744b96-error-1-diagram.png)
24+
25+
In a pre-swap or swap related error, the user will end up with the same tokens they started with on their initial chain (e.g. ATOM on Neutron in this example)
26+
27+
1. **Post-swap failures:**
28+
* **Description**: These are failures that occur on the sequence of transfers between the swap venue chain and the user's destination chain, after the user's origin tokens have already been successfully swapped for their desired destination asset.
29+
* **Outcome / What to Expect**: The user's newly purchased destination asset tokens will be transferred to their address on the swap chain. (This is the address passed to `chains_to_addresses` in `/fungible/msgs` for the chain where the swap takes place, which is given by `swap_venue.chain_id` in the response from `/fungible/route`)
30+
* **Common failure sources:**
31+
* Inactive relayers on a channel allow a packet to timeout
32+
* The user / frontend provides an invalid address for the destination chain
33+
* An IBC client on the destination chain has expired
34+
* **Examples:** Consider a route where the source asset is ATOM on Neutron, the destination asset is STRIDE on Stride, and the swap takes place on Osmosis:
35+
* Suppose the swap took place and the transfer to Stride has been initiated, but the Relayer between Osmosis and Stride is down. So the packet’s timeout occurs after 5 minutes. When the Relayer comes back online after 8 minutes, it relays a timeout message to Osmosis, releasing the user’s STRIDE, which gets forwarded to their Osmosis address
36+
37+
![In a post-swap error, the user will end up with their destination asset tokens in their address on the chain where the swap took place (e.g. STRIDE on Osmosis in this example)](/images/5c93590-error-type-2.png)
38+
39+
In a post-swap error, the user will end up with their destination asset tokens in their address on the chain where the swap took place (e.g. STRIDE on Osmosis in this example)
40+
41+
## Axelar Failures
42+
43+
Axelar transfers can be tracked on [Axelarscan](https://axelarscan.io/). Often, Axelar transfers are delayed by Axelar's relayer or execution services. If a transaction is taking longer than expected, users can visit Axelarscan, find their transaction, and manually execute the steps needed to get the transfer through. See the [Axelar docs](https://docs.axelar.dev/dev/general-message-passing/recovery) for details on how to use Axelarscan.
44+
45+
Internally, the Skip API uses Axelar's General Message Passing service to move assets between EVM and Cosmos. There are similar failure modes for Axelar as there are for IBC:
46+
47+
1. **Swap failures**
48+
* **What:** Axelar GMP takes user assets from an EVM chain to the swap chain. The swap can still fail at this point due to a timeout or slippage.
49+
* **Outcome / What to Expect:** The user receives the Axelar-transferred token on the swap chain at their recovery address.
50+
* **Common failure sources:**
51+
* Slow relaying from Axelar causes a timeout, and the swap is not attempted.
52+
* Slippage (the amount out for the swap turns out to be less than the user's specified minimum, i.e. their slippage exceeds their tolerance)
53+
2. **Post-swap failures**
54+
* Once the swap is executed, Axelar is no longer involved, and the same rules that apply to IBC post-swap failures apply here, so the **Post-swap failures** section above applies.
55+
56+
## CCTP Failures
57+
58+
Routes that use CCTP transfers rely on Circle to produce attestations. The Circle attestation service waits for a specified number of on-chain block confirmations before producing an attestation. The number of block confirmations required is specified by Circle in their documentation [here](https://developers.circle.com/stablecoins/docs/required-block-confirmations).
59+
60+
If Circle's attestation service experiences an outage, malfunction, or otherwise becomes unresponsive, CCTP transfers will continue to burn assets on the source chain, but will not be able to mint assets on the destination chain. In this case, funds that have been burned to initiate a CCTP transfer will be inaccessible until the Circle attestation service recovers.
61+
62+
## Hyperlane Failures
63+
64+
Each Hyperlane token transfer route is secured by an Interchain Security Module (ISM) designated by the deployer of the Hyperlane Warp Route Contracts (the interface to send tokens across chains using Hyperlane). The ISM defines the requirements for a message to be successfully processed on the destination chain.
65+
66+
The most common ISM is a Multisig ISM where "Validators" of a specific Hyperlane route sign attestations that a specific message on an origin chain is a valid message to be processed on the destination chain. In the case where the set of Validators have not hit the required signature threshold to successfully process a Hyperlane message on the receiving chain, funds will not be accessible by the user on either chain until the threshold is met (once met, funds will be sent to the user on the destination chain). This generalizes to the different requirements for different ISMs. The Hyperlane documentation explains the different types of ISMs in more detail: [https://docs.hyperlane.xyz/docs/reference/ISM/specify-your-ISM](https://docs.hyperlane.xyz/docs/reference/ISM/specify-your-ISM)
67+
68+
<Warning>
69+
70+
**Failures might occur for each transaction in a multi-tx sequence**
71+
72+
In the event of a multi-tx route, each transaction may suffer from the kinds of failures noted above. This means it's technically inaccurate to say that tokens will always end up on the initial chain or the chain where the swap takes place. More accurately, tokens may end up on each chain where a transaction is initiated or the chain where the swap takes place.
73+
74+
For instance, if a pre-swap failure takes place on the second transaction in a sequence, the tokens will end up on the chain that transaction targeted. In our example above, if the transfer from Cosmos Hub to Osmosis required a separate user transaction and the Neutron to Hub leg of the route succeeded in the first transaction, the ATOM tokens would end up in the user's account on the Hub if the swap exceeds maximum slippage.
75+
</Warning>
76+
77+
<Check>
78+
We're working to make these failures even less common
79+
80+
* In the short term, we're working to add packet tracking + live relayer + client status to the API to help identify when packets get stuck and prevent folks from using channels where they're likely to get stuck in the first place
81+
* In the medium term, we are working to add priority multi-hop relaying into the API.
82+
* In the long term, we're working to build better incentives for relaying, so relayers don't need to run as charities. (Relayers do not receive fees or payment of any kind today and subsidize gas for users cross-chain)
83+
84+
If you'd like to learn more, you can reach us easily at support@skip.money or in [our developer support channel on TG](https://t.me/+3y5biSyZRPIwZWIx)
85+
86+
87+
</Check>
88+
89+
<Check>
90+
Want to help us get better? Have questions or feedback?
91+
92+
You can reach us easily by joining [our Discord](https://skip.money/discord) and grabbing the "Skip API Developer" role.
93+
</Check>

0 commit comments

Comments
 (0)
Please sign in to comment.