From 594f51317c3e03795a9909822ba348dc808cd16b Mon Sep 17 00:00:00 2001 From: plubber <51789398+ericHgorski@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:51:43 -0400 Subject: [PATCH] fix: links, typos, improve language clarity (#225) Co-authored-by: Not Jeremy Liu <31809888+NotJeremyLiu@users.noreply.github.com> --- docs/advanced-transfer/evm-transactions.mdx | 2 +- .../svm-transaction-details.mdx | 2 +- docs/client/gas-and-fee-tooling.mdx | 4 +- docs/client/getting-started.mdx | 4 +- docs/general/affiliate-fees.mdx | 24 +++--- docs/general/api-keys.mdx | 10 +-- docs/general/faq.mdx | 80 +++++++++---------- docs/general/{fe-info.mdx => fee-info.mdx} | 8 +- ...altime-transaction-and-packet-tracking.mdx | 62 +++++++------- docs/general/overview-and-typical-usage.mdx | 10 ++- docs/general/post-route-actions.mdx | 20 ++--- docs/general/quickstart-guide.mdx | 49 ++++++------ docs/general/smart-relay.mdx | 40 +++++----- .../supported-ecosystems-and-bridges.mdx | 8 +- docs/mint.json | 2 +- docs/swagger.yml | 4 +- docs/widget/configuration-options.mdx | 2 +- 17 files changed, 166 insertions(+), 165 deletions(-) rename docs/general/{fe-info.mdx => fee-info.mdx} (82%) diff --git a/docs/advanced-transfer/evm-transactions.mdx b/docs/advanced-transfer/evm-transactions.mdx index 9b9d24ff..8b87b2e5 100644 --- a/docs/advanced-transfer/evm-transactions.mdx +++ b/docs/advanced-transfer/evm-transactions.mdx @@ -1,5 +1,5 @@ --- -title: 'EVM Transactions Intro' +title: 'EVM Transactions' description: 'This doc covers how to interact with the EvmTx type returned by the Skip Go API' --- diff --git a/docs/advanced-transfer/svm-transaction-details.mdx b/docs/advanced-transfer/svm-transaction-details.mdx index 45dbf36a..d2beb9bb 100644 --- a/docs/advanced-transfer/svm-transaction-details.mdx +++ b/docs/advanced-transfer/svm-transaction-details.mdx @@ -1,5 +1,5 @@ --- -title: 'SVM Transactions Intro' +title: 'SVM Transactions' description: 'This document explains how to use Skip Go API and Client TypeScript Package to construct SVM transactions.' --- diff --git a/docs/client/gas-and-fee-tooling.mdx b/docs/client/gas-and-fee-tooling.mdx index 1bc539d0..e301a66b 100644 --- a/docs/client/gas-and-fee-tooling.mdx +++ b/docs/client/gas-and-fee-tooling.mdx @@ -87,7 +87,7 @@ This field in `ExecuteRouteOptions` allows you to override our default gas price `getGasPrice?: (chainID: string) => Promise;` -The argument is a function that takes in a chain id and returns a gas price for that chain as a `GasPrice` object from CosmJS +The argument is a function that takes in a chain ID and returns a gas price for that chain as a `GasPrice` object from CosmJS ```text JavaScript type GasPrice = { @@ -100,7 +100,7 @@ If you provide a function that only returns a price for a subset of chains, the ### `ExecuteRouteOptions.gasAmountMultiplier` -This field in `ExecuteRouteOptions` allows you to override the default gas multiplier used in the SDK by default. (The default value is 1.5). Increases this value gives you higher confidence that your transaction will not run out of gas while executing, but increases the fee for the end user. +This field in `ExecuteRouteOptions` allows you to override the default gas multiplier used by default in the SDK. The default value is 1.5. Increasing this value provides higher confidence that transactions will not run out of gas while executing, but increases the fee for the end user. The gas multiplier increases a transaction's `gasAmount` multiplicatively. To get a final gas amount, the router: diff --git a/docs/client/getting-started.mdx b/docs/client/getting-started.mdx index cbf9371d..76e364b0 100644 --- a/docs/client/getting-started.mdx +++ b/docs/client/getting-started.mdx @@ -109,7 +109,7 @@ const chains = await client.chains({ }); ``` -#### Get a map of assets by chain id +#### Get a map of assets by chain ID Return type will be `Record` @@ -121,7 +121,7 @@ const assets = await client.assets({ includeSvmAssets: true, }); -// get assets filtered by chain id +// get assets filtered by chain ID const assets = await client.assets({ chainID: 'cosmoshub-4' includeEvmAssets: true, diff --git a/docs/general/affiliate-fees.mdx b/docs/general/affiliate-fees.mdx index 9c7c6584..c2b6598f 100644 --- a/docs/general/affiliate-fees.mdx +++ b/docs/general/affiliate-fees.mdx @@ -5,9 +5,9 @@ description: "This page covers how integrators can earn affiliate fees on swaps. ### Overview -Many teams use Skip Go API as a source of a revenue for their project by charging fees on swaps. (Charging fees on transfers will be possible in the future!). We refer to these fees throughout the product and documentation as "affiliate fees" +Many teams use Skip Go as a source of a revenue for their project by charging fees on swaps. (Charging fees on transfers will be possible in the future!). We refer to these fees throughout the product and documentation as "affiliate fees" -Skip Go API's affiliate fee functionality is simple but flexible -- supporting a large variety of bespoke fee collection scenarios: +Skip Go's affiliate fee functionality is simple but flexible -- supporting a large variety of bespoke fee collection scenarios: * Set your desired fee level on each swap (so you can offer lower fees to your most loyal users) * Set the account that receives the fee on each swap (so you can account for funds easily & separate revenue into different tranches) @@ -16,16 +16,16 @@ Skip Go API's affiliate fee functionality is simple but flexible -- supporting a ### Affiliate Fees Work 1. **At this time, affiliate fees can only be collected on swaps**. We do not support collecting affiliate fees on routes that only consist of transfers (e.g. CCTP transfers, IBC transfers, etc...) even when there are multi-hop transfers. Please contact us if charging fees on transfers is important to you -2. **Affiliate fees are collected on the chain where the last swap takes place**: Skip Go API aggregates over swap venues (DEXes, orderbooks, liquid staking protocols, etc...) on many different chains. Some routes even contain multiple swaps. For each individual cross-chain or single chain swap where you collect a fee, the fee is applied on the last swap and sent to an address you specify on the chain where the last swap takes place. -3. **Affiliate fees are collected/denominated in the output token of each swap**: For example, if a user swaps OSMO to ATOM, your fee collection address will earn a fee in ATOM. -4. **Affiliate fees are calculated using the minimum output amount, which is set based on our estimated execution price after accounting for the user's slippage tolerance** : For example, consider an ATOM to OSMO swap where min amount out is 10 uosmo and the cumulative fees are 1000 bps or 10%. If the swap successfully executes, the affiliate fee will be 1 uosmo. It will be 1 uosmo regardless of whether the user actually gets 10, 11, or 12 uosmo out of the swap. +2. **Affiliate fees are collected on the chain where the last swap takes place**: Skip Go aggregates over swap venues (DEXes, orderbooks, liquid staking protocols, etc...) on many different chains. Some routes even contain multiple swaps. For each individual cross-chain or single chain swap where you collect a fee, the fee is applied on the last swap and sent to an address you specify on the chain where the last swap takes place +3. **Affiliate fees are collected/denominated in the output token of each swap**: For example, if a user swaps OSMO to ATOM, your fee collection address will earn a fee in ATOM +4. **Affiliate fees are calculated using the minimum output amount, which is set based on our estimated execution price after accounting for the user's slippage tolerance** : For example, consider an ATOM to OSMO swap where min amount out is 10 uosmo and the cumulative fees are 1000 bps or 10%. If the swap successfully executes, the affiliate fee will be 1 uosmo. It will be 1 uosmo regardless of whether the user actually gets 10, 11, or 12 uosmo out of the swap ### How to Use Affiliate Fees There are two simple steps involved in using affiliate fees: -1. **Incorporate the fee into the quote** : You need to request the route & quote with the total fee amount (in basis points) you will collect, so Skip Go API can deduct this automatically from the estimated `amount_out` it returns to the user. This ensures the quote you show the user already accounts for your fee, and they won't receive any unexpectedly low amount. -2. **Set the address(es) to receive the fee**: You also need to tell Skip Go API the exact address(es) to send the fee revenue to. You need to pass a list of addresses and specify a fee amount (in basis points) for each to collect. +1. **Incorporate the fee into the quote** : You need to request the route & quote with the total fee amount (in basis points) you will collect, so Skip Go can deduct this automatically from the estimated `amount_out` it returns to the user. This ensures the quote you show the user already accounts for the fee, and they won't receive any unexpectedly low amount. +2. **Set the address(es) to receive the fee**: You also need to tell Skip Go the exact address(es) to send the fee revenue to. You need to pass a list of addresses and specify a fee amount (in basis points) for each to collect. #### Fees with /route and /msgs @@ -38,18 +38,18 @@ When using `/route` and `/msgs`, you incorporate the fee into the quote when you 1. The sum of `basis_points_fee` values across all affiliates should equal `cumulative_affiliate_fee_bps` 2. If you pass any addresses that are not valid on the chain where the swap will take place, the request will return a `400` error -#### Fees with /msgs\_direct +#### Fees with `/msgs_direct` - **/route and /msgs recommended over /msgs\_direct** + **`/route` and `/msgs` recommended over `/msgs_direct`** We generally recommend integrators use `/route` and `/msgs` rather than `/msgs_direct`. The complexity you must manage below is part of the reason for this recommendation. -1. Set `affiliates`to a list of\` `Affiliate` objects, where each corresponds to an address that will receive a portion of the fees if the swap takes place on the chain where that address is located. ( Within an `Affiliate` object, `address` gives the address, and `basis_points_fee` gives the fee amount). - 1. You should pass a set of affiliate addresses for every chain where the swap _might_ take place. (You can get this list by querying the `/v2/fungible/swap_venues` endpoint for the list of all `swap_venues` and grabbing the `chain_id` for each). This is required because `/msgs_direct` is determining the route, so we don't know which chain the swap will take place on when calling it. - 2. You should ensure that the sums of `basis_points_fee` for the sets of addresses you pass for each chain are equivalent. (For example, if you pass osmo1... addresses and neutron1... addresses, the sum of the `basis_points_fee` values for the osmo1... addresses must be the same as the sum for the neutron1... addresses.) You will receive an error if your fee sums are non-equivalent. (The error is necessary because we don't know which fee amount to simulate with.) +1. Set `affiliates`to a list of\` `Affiliate` objects, where each corresponds to an address that will receive a portion of the fees if the swap takes place on the chain where that address is located. (Within an `Affiliate` object, `address` gives the address, and `basis_points_fee` gives the fee amount). + 1. You should pass a set of affiliate addresses for every chain where the swap _might_ take place. (You can get this list by querying the `/v2/fungible/swap_venues` endpoint for the list of all `swap_venues` and grabbing the `chain_id` for each). This is required because `/msgs_direct` determines the route, so we don't know which chain the swap will take place on when calling it. + 2. You should ensure that the sums of `basis_points_fee` for the sets of addresses you pass for each chain are equivalent. (For example, if you pass osmo1... addresses and neutron1... addresses, the sum of the `basis_points_fee` values for the osmo1... addresses must be the same as the sum for the neutron1... addresses.) You will receive an error if your fee sums aren't equivalent. (The error is necessary because we don't know which fee amount to simulate with.) **Want to help us get better? Have questions or feedback?** diff --git a/docs/general/api-keys.mdx b/docs/general/api-keys.mdx index 41604de5..16efffc7 100644 --- a/docs/general/api-keys.mdx +++ b/docs/general/api-keys.mdx @@ -27,13 +27,13 @@ Technically, you can access most of the basic functionality of the Skip Go API w - **No rate limit**: Integrators that do not pass a valid API key in their requests will be subject to a restrictive global rate limit, shared with all other unauthenticated users. - **Improved fee revenue share pricing**: Unauthenticated integrators will be subject to a 25% revenue share on their fee revenue by default. Authenticated integrators who use API keys will be subject to a cheaper 20% revenue share by default. - **Access to privileged features:** Integrators who authenticate with an API key will receive access to premium features that we cannot offer to the general public (e.g. Gas estimation APIs, universal balance query APIs, etc...) -- **Metrics on your volume and revenue:** Authenticated integrators will receive access to monthly statistics regarding their total swap and transfer volume and the amount of fee revenue they've earned. They will also receive transaction data for taxes annually. +- **Metrics on your volume and revenue:** Authenticated integrators will receive access to monthly statistics regarding their total swap and transfer volume and the amount of fee revenue they've earned. They will also receive annual transaction data for taxes. ## How to get an API Key ### 1\. Request an API Key -Open a support ticket on our [Discord](https://skip.build/discord) and tell our customer support that you'd like an API key. \*\* +Open a support ticket on our [Discord](https://skip.build/discord) and tell our customer support that you'd like an API key. Please provide the following information in your request to help us get to know your project: @@ -47,7 +47,7 @@ The customer support team member at Skip will establish an official channel of c **You should store the API key immediately when you create it. We do not store your raw API key in our server for security reasons, so we will not be able to access it for you if you lose it.** -It is important to keep your API key private: Anyone with your API key can make requests to the Skip Go API as you, getting access to your rate limit, privileged features, and affecting your revenue and volume statistics. +It is important to keep your API key private. Anyone with your API key can make requests to the Skip Go API as you, getting access to your rate limit, privileged features, and affecting your revenue and volume statistics. ## How to use an API key @@ -92,7 +92,7 @@ const client = new SkipClient({ ### Setup a Proxy to Receive Skip Go API Requests and Add the API Key -To keep your API key secure and private, we recommend that you proxy the API requests from the frontend to your own backend--where you can add your API key in the header before forwarding the request to Skip Go API. +To keep your API key secure and private, we recommend that you proxy the API requests from the frontend to your own backend--where you can add your API key in the header before forwarding the request to the Skip Go API. The snippets below show you how to use Next.js/Vercel for this kind of proxying. It only takes a moment to set up. @@ -175,7 +175,7 @@ SKIP_API_KEY= ## How to Request Volume & Revenue Statistics -Just return to your official communication channel with Skip (probably a Telegram channel) and request the data. We will be able to share monthly reports. Eventually, we will create a customer portal and dashboards, so you'll have access to all the data you need continuously in a self-service manner. +Just return to your official communication channel with Skip (probably a Telegram channel) and request the data. We can share monthly reports. Eventually, we will create a customer portal with dashboards, so you'll have access to all the data you need in a self-service manner. **Want to help us get better? Have questions or feedback?** diff --git a/docs/general/faq.mdx b/docs/general/faq.mdx index eef2ce03..95a8bbb9 100644 --- a/docs/general/faq.mdx +++ b/docs/general/faq.mdx @@ -4,20 +4,20 @@ title: "FAQ" ### General / Background -#### How can I get help using the Skip Go API? +#### How can I get help using Skip Go? -You can reach us easily at support@skip.build or in [our developer support channel on TG](https://t.me/+3y5biSyZRPIwZWIx) +You can reach us easily at support@skip.build or in [our developer support channel on Telegram](https://t.me/+3y5biSyZRPIwZWIx) -#### Who uses the Skip Go API? +#### Who uses Skip Go? -Many teams use the Skip Go API to make it easier for them to build multi-chain flows, including: +Many teams use Skip Go to make it easier for them to build multi-chain flows, including: * Every major interchain wallet (Keplr, Leap, IBC wallet, Terra Station, all the metamask snap teams) * Osmosis asset deposit page * Many major interchain dapps (e.g. Stargaze, Stride, Astroport, Cosmos Millions) * Many interchain defi frontends (e.g. Coinhall, fortytwo.money) * TrustWallet -* Our own swapping frontend ([https://go.skip.build](https://go.skip.build)) +* Our own frontend ([https://go.skip.build](https://go.skip.build)) * ...and many more #### How many chains does Skip Go API support? @@ -31,7 +31,7 @@ More than 70+. We support: ...with more coming soon! -#### Which bridges and message passing protocols does Skip Go API support? +#### Which bridges and message passing protocols does Skip Go support? * IBC * Hyperlane @@ -41,7 +41,7 @@ More than 70+. We support: ...with more coming soon! -#### What DEXes does the Skip Go API support? +#### What DEXes does the Skip Go support? * Osmosis * Astroport across Terra, Neutron, Sei, and Injective @@ -49,29 +49,29 @@ More than 70+. We support: ...with many more coming soon -#### How do I get the Skip Go API to support my chain +#### How do I get Skip Go API to support my chain? -Please see the [Chain Support Requirements](/chain-support-requirements) document to ensure your chain meets the necessary requirements and submit the chain support request form linked in that doc. +Please see the [Chain Support Requirements](/support-requirements/chain-support-requirements) document to ensure your chain meets the necessary requirements and submit the chain support request form linked in that doc. #### How do I get the Skip Go API to support my token? -Please complete the necessary steps detailed in the [Token & Route Support Requirements](/token-support-requirements) doc. +Please complete the necessary steps detailed in the [Token & Route Support Requirements](/support-requirements/token-support-requirements) doc. #### How do I get the Skip Go API to support a route for a particular token to a remote chain? -Please complete the necessary steps detailed in the [Token & Route Support Requirements](/token-support-requirements) doc for the destination chain + token in question. +Please complete the necessary steps detailed in the [Token & Route Support Requirements](/support-requirements/token-support-requirements) doc for the destination chain and token in question. -#### How do I get the Skip Go API to route swaps to my swapping venue / DEX? +#### How do I get the Skip Go API to route swaps to my swap venue or DEX? -Please see the [Swap Venue Requirements](/skip-api-swap-venue-requirements) page to ensure your DEX meets the necessary requirements then submit the swap venue request form linked in that doc. +Please see the [Swap Venue Requirements](/support-requirements/swap-venue-requirements) page to ensure your DEX meets the necessary requirements then submit the swap venue request form linked in that doc. -#### How long does it take to build an application with Skip Go API? +#### How long does it take to build an application with Skip Go? 15-30 minutes #### Why do I keep getting rate limited? -You need to request an API key from the core team to use Skip Go API without limitations. +You need to request an API key from the core team to use Skip Go without limitations. Pass your API key into all requests with the `client_id` parameter. @@ -82,9 +82,9 @@ No, not at this time. We offer unlimited usage at zero cost. In the future we will introduce two pricing plans: 1. **Fee revenue sharing, unlimited usage**: For customers who use Skip Go API's fee functionality to charge their end-users fees on swaps, we will collect a portion of the fee revenue that you earn. Higher volume users will unlock lower fee tiers. -2. **API Usage Pricing**: For customers who do not charge fees, we will offer monthly and annual plans that allow usage of the API up to some number of requests per month. We will offer several pricing tiers, where higher tiers support higher rate limits and more monthly requests (e.g like coingecko, infura, etc..) +2. **API Usage Pricing**: For customers who do not charge fees, we will offer monthly and annual plans that allow usage of the API up to some number of requests per month. We will offer several pricing tiers, where higher tiers support higher rate limits and more monthly requests (similar to coingecko, infura, etc..) -#### I have questions, comments, or concerns about the API. How can I get in touch with you? +#### I have questions, comments, or concerns about Skip Go. How can I get in touch with you? You can reach us easily by joining [our Discord](https://skip.build/discord) and grabbing the "Skip Go Developer" role. @@ -97,20 +97,20 @@ You can reach us easily by joining [our Discord](https://skip.build/discord) and Users are responsible for the transactions they sign in all cases: 1. **If our smart contracts behave as expected (i.e. amount\_out exceeds min\_amount\_out signed by the user or amount\_in is less than max\_amount\_in signed), Skip will not offer users refunds, slippage rebates, or any other form of compensation for any reason**. Skip does not accept or bare any financial, legal, or practical responsibility for lost funds in the event a user or integrator believes a particular route is inadequate, bad, supoptimal, low liquidity, or otherwise not performant enough. -2. **If the smart contracts the Skip Go API depends on do not behave as expected, users who encounter and suffer bugs may report them in exchange for a bug bounty payment**. See the section on our bug bounty policy below +2. **If the smart contracts Skip Go depends on do not behave as expected, users who encounter and suffer bugs may report them in exchange for a bug bounty payment**. See the section on our bug bounty policy below. Integrators are solely and completely responsible for building UIs that maximally protect users from harming themselves by swapping or transferring at unfavorable prices. To help facilitate this goal, we provide: * Detailed information about quote quality, on-chain liquidity, fees, and price estimates in our API response objects (e.g. estimates of the USD value of amount in and amount out, on-chain price impact, etc...) -* Extensive guidance about how to build S.A.F.E. interfaces in our docs: [SAFE Swapping: How to protect users from harming themselves](/safe-swapping-how-to-protect-users-from-harming-themselves) -* Hand-on interface design feedback based on years of working with dozens of top interfaces +* Extensive guidance about how to build S.A.F.E. interfaces in our docs: [SAFE Swapping: How to protect users from harming themselves](/advanced-swapping/safe-swapping-how-to-protect-users-from-harming-themselves) +* Hands-on interface design feedback based on years of working with dozens of top interfaces #### Does Skip provide refunds to users if an interface created an transaction that called a Skip contract incorrectly? **No** 1. If an integrator or end user misuses one of our contracts intentionally or by accident (e.g. calls the contract with incorrect call data, sends tokens to a contract not designed to receive tokens), Skip bares no financial, legal, or operational responsibility for funds that may be lost as a result. -2. Skip and its affiliates do not have the ability to upgrade contracts to receive or "unstick" lost funds even if we wanted to. We do not own or control the contracts in the Skip Go API any more than you do. +2. Skip and its affiliates do not have the ability to upgrade contracts to receive or "unstick" lost funds even if we wanted to. We do not own or control the contracts in Skip Go any more than you do. #### Are there any circumstances under which Skip would offer a refund to an end user for any reason? @@ -122,7 +122,7 @@ Even in the event a user lost funds as a result of a bug, Skip does not claim an ### Bug Bounty Policy -#### Does Skip Go API offer a bug bounty? +#### Does Skip Go offer bug bounties? Skip may provide a financial bug bounty of up to $25,000 as compensation to users who report a reproducible catastrophic failure of a smart contract or other piece of software that the Skip team developed. Examples of catastrophic failures include: @@ -146,17 +146,17 @@ Please get in touch with our team at support@skip.build if you believe you have #### Where is the OpenAPI Swagger? -You can find the Swagger page here: [https://api-swagger.skip.build.](https://api-swagger.skip.build.) And you can find the OpenAPI generating doc here: [https://api-swagger.skip.build/swagger.yml](https://api-swagger.skip.build/swagger.yml) +You can find the Swagger page here: [https://api-swagger.skip.build](https://api-swagger.skip.build). And you can find the OpenAPI generating doc here: [https://api-swagger.skip.build/swagger.yml](https://api-swagger.skip.build/swagger.yml). #### What's the default IBC-Transfer timeout on the messages returned by `/fungible/msgs` and `/fungible/msgs_direct`? * 5 minutes -#### What technologies does Skip Go API use under the hood? +#### What technologies does Skip Go use under the hood? * IBC and... - * `ibc-hooks`: Enables the Skip Go API swap contracts to be executed as callbacks of IBC transfers, which enables constructing transactions that can transfer tokens to a chain with a swap venue, perform a swap, and transfer them out -- without multiple signing events / transactions. - * Skip Go API likely will not support DEXes on any chains that do not have `ibc-hooks` or equivalent functionality + * `ibc-hooks`: Enables the Skip Go swap contracts to be executed as callbacks of IBC transfers, which enables constructing transactions that can transfer tokens to a chain with a swap venue, perform a swap, and transfer them out -- without multiple signing events / transactions. + * Skip Go will likely not support DEXes on any chains that do not have `ibc-hooks` or equivalent functionality * `Packet-forward-middleware`(PFM): Enables incoming IBC transfers from one chain to atomically initiate outgoing transfers to other chains. This allows the chain with PFM to function as the intermediate chain on a multi-hop route. This is especially valuable for chains that issue assets for use throughout the interchain (e.g. Stride + stATOM, Noble + USDC, Axelar + axlUSDC) * (This [article we wrote](https://ideas.skip.build/t/how-to-give-ibc-superpowers/81) goes into more detail about both technologies and how to adopt them on your chain) * [Axelar](https://axelar.network/): A cross-chain messaging protocol that supports a wide variety of EVM chains and connects to Cosmos @@ -165,31 +165,31 @@ You can find the Swagger page here: [https://api-swagger.skip.build.](https://ap #### How do affiliate fees work? -* Affiliate fees are fees developers using our API charge their end-users on swaps. We support multiple parties taking and sharing fees. For example, if a defi frontend uses a swap widget a wallet team builds and distributes, the makers of the widget and the users of the widget can separately charge affiliate fees. +* Affiliate fees are fees developers using Skip Go charge their end-users on swaps. We support multiple parties taking and sharing fees. For example, if a defi frontend uses a swap widget a wallet team builds and distributes, the makers of the widget and the users of the widget can separately charge affiliate fees. * Fees are calculated in basis points or "bps". One basis point equals one one-hundredth of a percent. So 100 bps = 1% fee * **Affiliate fees are calculated based off the minimum amount out and are taken/denominated in the output token.** For example, consider an ATOM to OSMO swap where min amount out is 10 uosmo and the cumulative fees are 1000 bps or 10%. If the swap successfully executes, the affiliate fee will be 1 uosmo. It will be 1 uosmo regardless of whether the user actually gets 10, 11, or 12 uosmo out of the swap. -* **When performing a swap with an exact amount in, affiliate fees are accounted for in the `amount_out` returned by `/route`**. More plainly, the Skip Go API subtracts off expected affiliate fees prior to the `amount_out` calculation, so that it represents an accurate estimate of what the user will receive at the end of the swap, net of fees. To be exact, the user will probably receive more than the amount out because the actual fee is not known at the time of this calculation / estimate. It's not known until later when slippage is set. So the user will end up paying `slippage_percent`\*`amount_out` less than the API predicts. This is good for the user because the estimated out +* **When performing a swap with an exact amount in, affiliate fees are accounted for in the `amount_out` returned by `/route`**. More plainly, the Skip Go API subtracts off expected affiliate fees prior to the `amount_out` calculation, so that it represents an accurate estimate of what the user will receive at the end of the swap, net of fees. To be exact, the user will probably receive more than the amount out because the actual fee is not known at the time of this calculation / estimate. It's not known until later when slippage is set. So the user will end up paying `slippage_percent`\*`amount_out` less than the API predicts. This is good for the user because the estimated amount out will likely be lower than the actual amount they receive, offering a buffer that protects the user from the effects of slippage. #### Why does `/assets_from_source` only return assets that are reachable via transfers but not swaps? We're considering adding support for swappable destinations to `/assets_from_source`, but we're not prioritizing it because almost every asset is reachable via swapping from every other asset. So for 99.99% of use cases, this endpoint would just return a massive amount of fairly uninformative data, if we added destinations reachable via swaps. -#### Why does Skip Go API sometimes say a route doesn't exist when it should (e.g. transferring ATOM to Stargaze)? +#### Why does the Skip Go API sometimes say a route doesn't exist when it should (e.g. transferring ATOM to Stargaze)? There are two common reasons Skip Go API is missing a route that a user thinks might exist: 1. **No one has ever used it:** By default, the Skip Go API does not recommend channels that have never been used or denoms that it has not seen. For example, if no one has transferred Neutron to Stargaze, the Skip Go API will not recommend a route to do so -- even if a direct connection exists between the two chains. -2. **Expired clients:** Frequently, existing connections between chains expire when they're not used for a period of time that exceeds the "light client trusting period. Skip Go API indexes all chains every couple of hours to identify these cases and prevent users from accidentally attempting transfers. +2. **Expired clients:** Frequently, existing connections between chains expire when they're not used for a period of time that exceeds the "light client trusting period. The Skip Go API indexes all chains every couple of hours to identify these cases and prevent users from accidentally attempting transfers. -_A common gotcha:_ `/assets_from_source` only returns assets reachable in a single transaction by default. If you'd like to have access to routes that require multiple transactions, set the `allow_multi_tx` flag to `True` in the input. +_A common gotcha:_ `/assets_from_source` only returns assets reachable in a single transaction by default. If you'd like to have access to routes that require multiple transactions, set the `allow_multi_tx` flag to `true` in the input. #### How long does relaying an IBC packet take? -This is a great question and the best answer that exists is: It depends on many factors, including how many relayers are covering a particular channel, block times, the time-to-finality of the source chain, whether relayers are live, how many packets relayers are waiting to batch together, and much more... +It depends on many factors, including how many relayers are covering a particular channel, block times, the time-to-finality of the source chain, whether relayers are live, how many packets relayers are waiting to batch together, and much more... **In short, it can range from several seconds to minutes (or never) in the worst case.** After a timeout window, a packet won't be valid on the destination chain when it gets relayed. This timeout is set to 5 minutes for all packets created via the Skip Go API. It's important to understand what happens to user tokens in the event of timeouts. You can read about that in [Cross-chain Failure Cases](../advanced-transfer/handling-cross-chain-failure-cases) -For now, we recommend making a small warning or disclaimer to users on your application, including some variant of the following: +For now, we recommend making a small warning or disclaimer to users on your application, similar to the following: > This swap contains at least one IBC transfer. > @@ -323,25 +323,23 @@ We recommend setting Cosmos chain gas prices using the chainapsis keplr-chain-re * Transactions almost always make it on chain * Gas prices are very cheap -- so overestimation is not costly -(Gas price is actually decided on a per validator basis for most chains. It's not a - -Shortly, the Skip Go API will surface recommended gas price too, and we will release a client-side library that will abstract away this area of concern. +Soon, the Skip Go API will surface recommended gas price too, and we will release a client-side library that will abstract away this area of concern. #### How should I set gas amount for Cosmos transactions? -We recommend using the [Gas and Fee Tooling](/gas-and-fee-tooling) available in the [Skip Go Client TypeScript Package](https://www.npmjs.com/package/@skip-go/client). +We recommend using the [Gas and Fee Tooling](/client/gas-and-fee-tooling) available in the [Skip Go Client TypeScript Package](https://www.npmjs.com/package/@skip-go/client). #### What does it mean when the docs say an endpoint is in "ALPHA" or "BETA"? -This means we may make API breaking changes to them at any time. +This means we may make breaking changes to them at any time. #### What does `cumulative_fee_bps` in `/route` mean? This is where you specify the fee amount in bps aka "bips". (1 bp = 1 / 100th of a percent; 100 bps = 1%) -By specifying it in route, the API can adjust the quote that it gives back to you, so that it shows output token estimate net of fees. This ensures the amount the end user gets out of the swap is always in-line with their expectations. +By specifying it in route, the Skip Go API can adjust the quote that it gives back to you, so that it shows output token estimate net of fees. This ensures the amount the end user gets out of the swap always aligns with their expectations. -The parameter uses the word "cumulative" (i.e. summing over a set) because the API supports multiple partners charging affiliate fees. This parameter should be set to the sum of all of those component fees. (For example, if a widget provider charges a 5 bp fee, and the frontend developer integrating that widget charges a 10 bp fee, `cumulative_fee_bps=15` +The parameter uses the word "cumulative" (i.e. summing over a set) because the API supports multiple partners charging affiliate fees. This parameter should be set to the sum of all of those component fees. (For example, if a widget provider charges a 5 bp fee, and the frontend developer integrating that widget charges a 10 bp fee, `cumulative_fee_bps=15`) ### Misc @@ -355,5 +353,5 @@ The parameter uses the word "cumulative" (i.e. summing over a set) because the A **Want to help us get better? Have questions or feedback?** -You can reach us easily at support@skip.build or in [our developer support channel on TG](https://t.me/+3y5biSyZRPIwZWIx) +You can reach us easily at support@skip.build or in [our developer support channel on Telegram](https://t.me/+3y5biSyZRPIwZWIx) \ No newline at end of file diff --git a/docs/general/fe-info.mdx b/docs/general/fee-info.mdx similarity index 82% rename from docs/general/fe-info.mdx rename to docs/general/fee-info.mdx index df4e8072..d9e2af83 100644 --- a/docs/general/fe-info.mdx +++ b/docs/general/fee-info.mdx @@ -1,11 +1,11 @@ --- title: "Getting Fee Info" -description: "This doc describes functionality in Skip Go API for accessing and understanding user-facing fees" +description: "Understand how Skip Go handles user-facing fees" --- ## Background -This doc describes functionality in Skip Go API for accessing standardized information about the various fees that a user can incur while swapping or transferring. Common fees include: +This doc describes functionality in Skip Go for accessing standardized information about the various fees that a user can incur while swapping or transferring. Common fees include: * Affiliate fees (e.g. fees you charge the user for swapping on your frontend) * Bridge and relayer fees @@ -19,11 +19,11 @@ This doc describes functionality in Skip Go API for accessing standardized infor Each `Fee` object in the array will have the following attributes: * `fee_type`: Enum giving the kind of fee — `SMART_RELAY` , `SWAP` , `BRIDGE`, `RELAY` , `GAS` -* `bridge_id` : If the fee is a relayer fee (`RELAY`) or a bridge fee (`BRIDGE`), this gives the ID of the bridge charging the fee (or the bridge where the relayer is providing service) +* `bridge_id` : If the fee is a relayer fee (`RELAY`) or a bridge fee (`BRIDGE`), this gives the ID of the bridge charging the fee (or the bridge where the relayer is providing a service) * `amount` : The amount of the fee (expressed in the token the fee will be charged in) * `usd_amount`: Estimated USD value of the fee * `origin_asset` : An `Asset` object containing useful metadata for displaying and identifying the token in which the fee is denominated -* `chain_id` : Chain id where the fee will be collected +* `chain_id` : Chain ID where the fee will be collected * `denom` : Denom of the token in which the fee is denominated * `tx_index`: The zero-indexed identifier of the transaction where the user will incur this fee (For multi-transaction routes, fees may be incurred after the first transaction) * `operation_index`: The zero-indexed entry in the operations array where the user will incur this fee diff --git a/docs/general/multi-chain-realtime-transaction-and-packet-tracking.mdx b/docs/general/multi-chain-realtime-transaction-and-packet-tracking.mdx index 58a062be..d1286b93 100644 --- a/docs/general/multi-chain-realtime-transaction-and-packet-tracking.mdx +++ b/docs/general/multi-chain-realtime-transaction-and-packet-tracking.mdx @@ -1,13 +1,13 @@ --- title: "Transaction Tracking" -description: "This document covers the tooling provided in Skip Go API for tracking transaction status across multiple chains and bridge hops." +description: "This document covers the tooling provided in Skip Go for tracking transaction status across multiple chains and bridge hops." --- ## Background -The `/v2/tx` endpoints include unified APIs that broadcast transactions and provide insight into the status of transactions and their subsequent cross-chain actions over all the bridges we support. +The `/v2/tx` endpoints include unified APIs that broadcast transactions and provide insight into the status of transactions and their subsequent cross-chain actions. -You can use the `/v2/tx` endpoints to track the progress of a cross-chain transfer or swap, no matter how many chains or bridges the transfer touches, in realtime. (For more advanced use cases, the endpoints support tracking multiple distinct transfers initiated in a single transaction) +You can use the `/v2/tx` endpoints to track the progress of a cross-chain transfer or swap in realtime -- no matter how many chains or bridges the transfer touches. (For more advanced use cases, the endpoints support tracking multiple distinct transfers initiated in a single transaction). You can also use it to identify failure cases (e.g. a swap that fails due to slippage, an IBC transfer that fails due to inactive relayers) and determine where the user's tokens will become available. @@ -19,41 +19,40 @@ For example, if one of your end users initiates a swap that begins with ATOM on At a high-level, the transaction tracking works in two stages: -1. You must inform our tracking engine that you want a particular transaction tracked by submitting it to the chain via `/v2/tx/submit` or submitting it to your own Node RPC then calling `/v2/tx/track` -2. Query status at some regular interval to get updates on the progress of the transaction +1. Inform our tracking engine that you want to track a particular transaction by submitting it to the chain via `/v2/tx/submit` or submitting it to your own Node RPC then calling `/v2/tx/track` +2. Query the transaction status at some regular interval to get updates on it's progress **Tracking Multiple Independent Routes** - (You can use the endpoint to track multiple transfers initiated in a single transaction, where the status of transfer `i` is given by entry `i` in the `transfers` array. For example, I could transfer ATOM to the Cosmos Hub and OSMO to Osmosis in a single transaction and track them with `transfers[0]` and `transfers[1]` respectively) + You can use the endpoint to track multiple transfers initiated in a single transaction, where the status of transfer `i` is given by entry `i` in the `transfers` array. For example, I could transfer ATOM to the Cosmos Hub and OSMO to Osmosis in a single transaction and track them with `transfers[0]` and `transfers[1]` respectively. For a single transfer that has multiple hops (e.g. transferring ATOM to the Cosmos Hub then to Osmosis), you can track the status of each hop using the entries of `transfers[i].transfer_sequence` -The status endpoint provides a mixture of high-level fields to keep track of the basic progress of your route and low-level fields to drill all the way into the individual transactions that make up a single transfer. - +The status endpoint provides a mixture of high-level fields to keep track of the basic progress of your route and low-level fields to provide high visbility into the individual transactions that make up a single transfer. ### Important high-level `/v2/tx/status` fields Each entry in the `transfers` array corresponds to a single route that may contain many steps, and each entry in `transfer_sequence` will contain very detailed information about each step in that route. -But there a a few high-level fields in each `transfers` entry that you'll find useful no matter what your route does or what bridges it involves: +But there a few high-level fields in each `transfers` entry that you'll find useful no matter what your route does or what bridges it involves: * `state`: The basic status of your route. **This lets you report the basic state of the route to the user (e.g. in progress, failed, etc...)** * `STATE_SUBMITTED`: Indicates the transaction has been accepted for tracking but no on chain evidence has been found yet. * `STATE_ABANDONED`: Tracking has stopped after 30 minutes without progress. There is likely a relayer outage, an undetected out of gas error, or some other problem. * `STATE_PENDING`: The route is in progress and no errors have occurred yet - * `STATE_PENDING_ERROR`: The route is in progress and an error has occurred somewhere, but the error is currently propagating, so the user doesn't have their tokens returned yet. (This state will only occur for protocols that require an "acknowledgement" on the source chain to process an error. IBC only at this time) + * `STATE_PENDING_ERROR`: The route is in progress and an error has occurred somewhere, but the error is currently propagating, so the user doesn't have their tokens returned yet. (This state will only occur for protocols that require an _acknowledgement_ on the source chain to process an error. IBC only at this time) * `STATE_COMPLETED_SUCCESS`: The route has completed successfully and the user has their tokens on the destination (indicated by `transfer_asset_release`) - * `STATE_COMPLETED_ERROR`: The route errored somewhere and the user has their tokens unlocked in one of their wallets. Their tokens are either on the source chain, an intermediate chain, or the destination chain but as the wrong asset. (Again, `transfer_asset_release` indicates where the tokens are) + * `STATE_COMPLETED_ERROR`: The route errored somewhere and the user has their tokens unlocked in one of their wallets. Their tokens are either on the source chain, an intermediate chain, or the destination chain but in the wrong asset. ( `transfer_asset_release` indicates where the tokens are) * `next_blocking_transfer`: Gives the index of the entry in `transfer_sequence` that corresponds to the currently propagating transfer that is immediately blocking the release of the user's tokens -- `next_blocking_transfer.transfer_sequence_index` (it could be propagating forward or it could be propagating an error ack backward). **This lets you tell the user exactly which operation is pending at a given time** * `transfer_asset_release`: Info about where the users tokens will be released when the route completes. This populates on `STATE_PENDING_ERROR`, `STATE_COMPLETED_SUCCESS`, or `STATE_COMPLETED_ERROR`. **This lets you tell the user where to recover their funds in the event of a success or failure** _(If you want to better understand how to predict this or where funds might end up, see [Cross-chain Failure Cases](../advanced-transfer/handling-cross-chain-failure-cases))_ - * `transfer_asset_release.released`: Boolean given whether the funds are currently available (If state is`STATE_PENDING_ERROR` , this will be `false` - * `transfer_asset_release.chain_id`: Chain where the assets are released or will be released. - * `transfer_asset_release.denom`: Denom of the tokens the user will have. + * `transfer_asset_release.released`: Boolean given whether the funds are currently available (if the state is`STATE_PENDING_ERROR` , this will be `false`) + * `transfer_asset_release.chain_id`: Chain where the assets are released or will be released + * `transfer_asset_release.denom`: Denom of the tokens the user will have ### Detailed Info: Using`transfer_sequence` -The `transfer_sequence` array consists of `TransferEvent` objects, which give detailed information about an individual transfer operation. The object acts as a wrapper around one details object for each bridge we support +The `transfer_sequence` array consists of `TransferEvent` objects, which give detailed information about an individual transfer operation. The object acts as a wrapper around one details object for each bridge we support: * `CCTPTransferInfo` * `IBCTransferInfo` @@ -61,48 +60,47 @@ The `transfer_sequence` array consists of `TransferEvent` objects, which give de * `HyperlaneTransferInfo` Each one contains slightly different data and statuses corresponding to the details of their bridge, but they all contain some standard info: - * `from_chain_id` * `to_chain_id` -* Transactions and block explorer links for all of the significant events in the transfer (send tx, receive tx, and sometimes ack tx) +* Transactions and block explorer links for all of the significant events in the transfer (send tx, receive tx, and sometimes acknowledge tx) * A status field giving the status of the transfer, which can vary based on bridge #### IBC Transfer Data The `state` field in the `IBCTransferInfo` entries in the `transfer_sequence` array have the following meanings: -* `TRANSFER_UNKNOWN`: The transfer state is unknown. -* `TRANSFER_PENDING` \- The send packet for the transfer has been committed and the transfer is pending. +* `TRANSFER_UNKNOWN`: The transfer state is unknown +* `TRANSFER_PENDING` \- The send packet for the transfer has been committed and the transfer is pending * `TRANSFER_PENDING_ERROR` \- There has been a problem with the transfer (e.g. the packet has timed out) but the user doesn't have their funds unlocked yet because the error is still propagating -* `TRANSFER_RECEIVED`\- The transfer packet has been received by the destination chain. It can still fail and revert if it is part of a multi-hop PFM transfer. -* `TRANSFER_SUCCESS` \- The transfer has been successfully completed and will not revert. -* `TRANSFER_FAILURE` \- The transfer has failed. +* `TRANSFER_RECEIVED`\- The transfer packet has been received by the destination chain. It can still fail and revert if it is part of a multi-hop PFM transfer +* `TRANSFER_SUCCESS` \- The transfer has been successfully completed and will not revert +* `TRANSFER_FAILURE` \- The transfer -`packet_txs` contain transaction hashes, chain IDs, and block explorer links for potentially 4 transactions: +`packet_txs` contain transaction hashes, chain IDs, and block explorer links for up to 4 transactions: * `send_tx`: The packet being sent from the source chain * `receive_tx`: The packet being received on the destination chain -* `timeout_tx`: The packet has being timed out on the destination chain +* `timeout_tx`: The packet being timed out on the destination chain * `acknowledge_tx`: The successful or failed acknowledgement of the packet on the source chain #### Axelar Transfer Data When one of the transfers is an Axelar transfer, the `transfer_sequence` array will give an `axelar_transfer` (`AxelarTransferInfo`), instead of an `ibc_transfer`, which contains different data because: -* Skip Go API may utilize send\_token or contract\_call\_with\_token (two underlying Axelar protocols) depending on which is cheaper and which is required to execute the user's intent +* The Skip Go API may utilize send\_token or contract\_call\_with\_token (two underlying Axelar protocols) depending on which is cheaper and which is required to execute the user's intent * Axelar does not have a notion of packets or acks, like IBC does * Axelar provides a nice high level UI (Axelarscan) to track the status of their transfers More precise details about all the fields are below: -* `type` : an enum of `AXELAR_TRANSFER_SEND_TOKEN` and `AXELAR_TRANSFER_CONTRACT_CALL_WITH_TOKEN`, which indicate whether the Axelar transfer is a \[Send Token\]([https://docs.axelar.dev/dev/send-tokens/overview](https://docs.axelar.dev/dev/send-tokens/overview)) or a \[Contract Call With Token\]([https://docs.axelar.dev/dev/general-message-passing/gmp-tokens-with-messages](https://docs.axelar.dev/dev/general-message-passing/gmp-tokens-with-messages)) transfer respectively. +* `type` : an enum of `AXELAR_TRANSFER_SEND_TOKEN` and `AXELAR_TRANSFER_CONTRACT_CALL_WITH_TOKEN` which indicate whether the Axelar transfer is a [Send Token](https://docs.axelar.dev/dev/send-tokens/overview) or a [Contract Call With Token](https://docs.axelar.dev/dev/general-message-passing/gmp-tokens-with-messages) transfer respectively. * `axelar_scan_link`: Gives the link to Axelar's bridge explorer (which can help track down and unstick transactions) * `state` field indicates the current state of the Axelar transfer using the following values: - * `AXELAR_TRANSFER_UNKNOWN` \- The transfer state is unknown. - * `AXELAR_TRANSFER_PENDING_CONFIRMATION` \- The transfer has been initiated is pending confirmation by the Axelar network. - * `AXELAR_TRANSFER_PENDING_RECEIPT` \- The transfer has been confirmed by the Axelar network and is pending receipt at the destination. - * `AXELAR_TRANSFER_SUCCESS` \- The transfer has been completed successfully and assets have been received at the destination. - * `AXELAR_TRANSFER_FAILURE` \- The transfer has failed. + * `AXELAR_TRANSFER_UNKNOWN` \- The transfer state is unknown + * `AXELAR_TRANSFER_PENDING_CONFIRMATION` \- The transfer has been initiated but is pending confirmation by the Axelar network + * `AXELAR_TRANSFER_PENDING_RECEIPT` \- The transfer has been confirmed by the Axelar network and is pending receipt at the destination + * `AXELAR_TRANSFER_SUCCESS` \- The transfer has been completed successfully and assets have been received at the destination + * `AXELAR_TRANSFER_FAILURE` \- The transfer has failed * `txs` field schema depends on the `type` of the transfer * If `type` is `AXELAR_TRANSFER_SEND_TOKEN`, there are 3 txs: * `send_tx` (initiating the transfer) @@ -175,7 +173,7 @@ This will walk through an example of how a developer would use the api to track In this particular example, we'll cover a simple 2-hop IBC transfer from axelar to the cosmoshub through osmosis. -_(Usage is similar for tracking Axelar transfers or transfers that include multiple hops over distinct bridges but the data structures change slightly depending on what underlying bridge is being used)_ +_Usage is similar for tracking Axelar transfers or transfers that include multiple hops over distinct bridges but the data structures change slightly depending on what underlying bridge is being used_ ### 1\. Call `/tx/submit` to broadcast a transaction diff --git a/docs/general/overview-and-typical-usage.mdx b/docs/general/overview-and-typical-usage.mdx index 5483a53e..2a9f14dd 100644 --- a/docs/general/overview-and-typical-usage.mdx +++ b/docs/general/overview-and-typical-usage.mdx @@ -4,8 +4,9 @@ title: 'Overview & Common Usage Patterns' ## Summary -This doc provides a high-level overview of the different kinds of methods available in the Skip Go API & describes how integrators typically use them in combination to create a cross-chain swapping frontend like [go.skip.build](https://go.skip.build) +This doc provides a high-level overview of the different kinds of methods available in the Skip Go API & describes how integrators typically use them in combination to create a cross-chain swapping frontend like [go.skip.build](https://go.skip.build). +See the [API reference](/api-reference/prod) for more information on each endpoint. ## Overview of Methods ### `/info` methods: Functionality for Retrieving General Purpose Info @@ -17,6 +18,7 @@ The most important `info` methods include: - `/v2/info/chains` (`SkipClient.chains`): Get info about all supported chains, including capabilities, address type, logo, etc... - `/v2/info/bridges`: Get basic info about all supported bridges, including logo and name + ### `/fungible` methods: Functionality for fungible token swaps and transfers The `/v2/fungible` endpoints & their counterparts in `SkipClient` provide APIs for cross-chain swaps and transfers of fungible tokens. @@ -25,7 +27,7 @@ In the background, the API provides automatic DEX aggregation, bridge routing, d The most important `fungible` methods include : -- `/v2/fungible/route` (`SkipClient.route`): Get a swap/transfer route and quote between a pair of tokens & chains (You can customize this request significantly to only consider particular DEXes, bridges; to add route splitting for better prices; and much more...) +- `/v2/fungible/route` (`SkipClient.route`): Get a swap/transfer route and quote between a pair of tokens & chains. You can customize this request significantly to only consider particular DEXes, bridges; to add route splitting for better prices; and much more. - `/v2/fungible/msgs` (`SkipClient.msgs` ): Generates the transaction data for the transaction(s) the user must sign to execute a given route - `/v2/fungible/msgs_direct` (`SkipClient.msgsDirect`) : Generates a route, quote, and associated transaction data at the same time - `/v2/fungible/venues`(`SkipClient.venues`): Get metadata for all supported swapping venues (DEXes, liquid staking protocols, etc...), including name and logo. @@ -42,6 +44,8 @@ The most important `tx` methods include: - `/v2/tx/track`(`SkipClient.trackTransaction`): Registers a transaction for tracking with Skip Go API (Often used instead of `/submit` when an integrator has their own chain nodes for submitting) - `/v2/tx/status` (`SkipClient.transactionStatus`) : Get the current status of a multi-hop transaction +[`/tx` API reference](https://docs.skip.build/go/api-reference/prod/transaction/post-v2txsubmit) + ## Typical Usage in Cross-chain Swapping Frontend On a cross-chain swapping and transferring frontend, integrators typically: @@ -60,7 +64,7 @@ On a cross-chain swapping and transferring frontend, integrators typically: 4. Use `/tx/track`(`SkipClient.trackTransaction`) to register the transaction for tracking (or `/tx/submit` to register and submit it on-chain) -5. Use `/status` (`SkipClient.transactionStatus`) to get the real-time status of the transaction as it progresses through multiple bridges/chains. +5. Use `/status` (`SkipClient.transactionStatus`) to get the real-time status of the transaction as it progresses across bridges and/or chains. ![](/images/a83beaf-CleanShot_2024-05-23_at_15.59.452x.png) diff --git a/docs/general/post-route-actions.mdx b/docs/general/post-route-actions.mdx index a2248355..3c3df388 100644 --- a/docs/general/post-route-actions.mdx +++ b/docs/general/post-route-actions.mdx @@ -3,21 +3,21 @@ title: "Post-Route Actions" description: "How to specify actions to perform after a route of transfers/swaps is completed" --- -Callers of the Skip Go API can specify actions to execute on the destination chain after a route transfer or swap is complete using the `post_route_handler` parameter of `/v2/fungible/msgs`as a part of the same transaction where the swap/transfer took place. +Use the `post_route_handler` parameter of `/v2/fungible/msgs` endpoint to define actions that will be executed on the destination chain after a route transfer or swap is completed. These actions are executed within the same transaction as the original swap or transfer. -This allows developers to build omni-chain and omni-token workflows where users can swap, liquid stake, deposit, buy an NFT, or take any other action starting from any chain or any token in Cosmos -- all in 1 transaction. +This handler allows developers to build omni-chain and omni-token workflows where users can swap, liquid stake, deposit, buy an NFT, or take any other action starting from any chain or any token in Cosmos -- all in a single transaction. This parameter currently supports: 1. CosmWasm contract calls on the destination chain -2. `autopilot` support for liquid staking interactions on Stride. +2. `autopilot` support for liquid staking interactions on Stride ### Background Info -All after route actions must have the following characteristics: +All `post_route` actions must have the following characteristics: -* **Permissionless:** Skip Go API can only support permissionless actions because the underlying protocols (e.g. ibc-hooks, packet-forward-middleware) derive the addresses they use to call contracts based on the origin of the transfer. This means one user originating on two different chains or starting with two different tokens will eventually call the final contract / module with different addresses. You can only reliably permission actions that you know will 1) always originate on the same chain and 2) always take the same path to the destination chain. In general, we recommend not making this assumption unless you are an interoperability expert -* **Single-token input:** The underlying IBC transfer protocol (ICS-20) doesn't support transferring more than 1 token denom in a single transfer message, so we can only send 1 denom of tokens to the final contract or module at a tme. That means the contract or module must not require multiple token denoms sent to it simultaneously. For example, a classic LP action where the user must provide tokens in both sides of the pool simultaneously would not work. +* **Permissionless:** Skip Go can only support permissionless actions because the underlying protocols (e.g. ibc-hooks, packet-forward-middleware) derive the addresses they use to call contracts based on the origin of the transfer. This means one user originating on two different chains or starting with two different tokens will eventually call the final contract / module with different addresses. You can only reliably permission actions that you know will 1) always originate on the same chain and 2) always take the same path to the destination chain. In general, we recommend not making this assumption unless you are an interoperability expert +* **Single-token input:** The underlying IBC transfer protocol (ICS-20) doesn't support transfers of more than 1 token denom in a single transfer message, so we can only send 1 token denom to the final contract or module at a time. This means the contract or module in the `post_route_handler` must not require multiple token denoms sent to it simultaneously. For example, a classic LP action where the user must provide tokens in both sides of the pool simultaneously would not work. @@ -25,7 +25,7 @@ All after route actions must have the following characteristics: Commonly, the first interaction with a contract is permissionless, but it awards the end-user some kind of permissioned authority to perform follow-on actions (e.g. staking enables unstaking + collecting rewards; depositing enables withdrawing and earning yield) or receipt tokens (e.g. LPing produces LP receipt tokens). -As a cross-chain caller, you should generally avoid contracts that implicitly delegate these authorities or give receipt tokens to the caller because the caller will depend on the path the user has taken over IBC. You should look for contracts to implicit authority delegation -- i.e. contracts that explicitly assign permissions to an address in the calldata that may be different than the caller and address sending the tokens. Examples of this pattern are: +As a cross-chain caller, you should generally avoid contracts that implicitly delegate these authorities or give receipt tokens to the caller because the caller will depend on the path the user has taken over IBC. You should look for contracts to imply authority delegation -- i.e. contracts that explicitly assign permissions to an address in the calldata that may be different than the caller and address sending the tokens. Examples of this pattern are: * Astroport’s `receiver` parameter in the `provide_liquidity` message * Mars’ `on_behalf_of` parameter in the `deposit` message @@ -37,7 +37,7 @@ We recommend setting these authority delegation parameters to the user's local a To call a CosmWasm contract on the destination chain, the following requirements must be satisfied: -1. The destination chain supports `ibc-hooks` & has CosmWasm. +1. The destination chain supports CosmWasm & `ibc-hooks`. 2. The chain in the route immediately before the destination chain supports IBC memos as well as `packet-forward-middleware`. To specify a CosmWasm contract call on the destination chain, pass a `wasm_msg` as the `post_route_handler` in the `/v2/fungible/msgs` call with: @@ -45,7 +45,7 @@ To specify a CosmWasm contract call on the destination chain, pass a `wasm_msg` * `contract_address`: The target contract address * `msg`: JSON string of the message to pass to the contract -Set the destination address in the `address_list` to be the address of the contract as well. +In addition, set the destination address in the `address_list` to the address of the contract. For example, this is a request for a transfer of USDC from Axelar to Neutron, with a post-route handler that swaps the USDC to Neutron using an Astroport pool on Neutron: @@ -89,7 +89,7 @@ The message returned from this request uses `ibc-hooks` on Neutron to perform th ### Autopilot -To use autopilot after route actions, the following requirements must be satisfied: +To use Autopilot after route actions, the following requirements must be satisfied: 1. The destination chain supports the `autopilot` module. Currently, this means the destination chain must be `stride-1`. 2. The chain in the route immediately before the destination chain supports IBC memos as well as `packet-forward-middleware`. diff --git a/docs/general/quickstart-guide.mdx b/docs/general/quickstart-guide.mdx index 1dd69ca2..7b7e471d 100644 --- a/docs/general/quickstart-guide.mdx +++ b/docs/general/quickstart-guide.mdx @@ -4,10 +4,10 @@ title: 'Quickstart Guide' ## Summary -This will walkthrough shows you how to get started with the API by performing a swap of USDC on Noble to TIA on Celestia. +This walkthrough shows you how to perform a swap of USDC on Noble to TIA on Celestia. - **Get in touch if you're having trouble** + **Having trouble? Get in touch** Please contact us if you believe the API doesn't conveniently support your desired user experience, or if you're confused about how to use it. @@ -17,7 +17,7 @@ You can reach us easily by joining [our discord](https://skip.build/discord) and ## Reference Docs -For detailed information on all the Skip Go API endpoints and functionality, please see our [reference docs](/api-reference/info/get-v2infochains). +For detailed information on Skip Go API endpoints and functionality, please see our [reference docs](/api-reference/prod/info/get-v2infochains). ## Example using @skip-go/client package @@ -32,11 +32,11 @@ npm i @skip-go/client ``` - **Additional dependencies and steps will be required for EVM & SVM Transactions** + **Additional dependencies and steps will be required for EVM & SVM transactions** -This example constructs a cross-chain swap between 2 Cosmos chains, but Skip Go API supports all major EVM chains & Solana. (See [Supported Ecosystems](/supported-ecosystems-and-bridges) for more info about which chains, routes, and tokens we support) +This example constructs a cross-chain swap between 2 Cosmos chains, but Skip Go API supports all major EVM chains & Solana (see [Supported Ecosystems](/general/supported-ecosystems-and-bridges) for more info about which chains, routes, and tokens we support). -If you'd like to perform a cross-chain swap that starts or ends on Solana or an EVM chain, you'll need to import additional dependencies and configure additional tx signers. After going through this tutorial, check out [EVM Transactions Intro](/evm-transactions) and [SVM Transactions Intro](/svm-transaction-details) if you need. +To perform cross-chain swaps involving Solana or an EVM chain, you'll need to import extra dependencies and configure additional transaction signers. Once you've completed this tutorial, feel free to red the [EVM Transactions](/advanced/transfer/evm-transactions) and [SVM Transactions](/advanced-transfer/svm-transaction-details) docs for more details. @@ -57,7 +57,7 @@ For this example, we are going to use Phantom wallet: npm i @solana/wallet-adapter-phantom ``` -Now, let's create the SkipClient instance with the signers for each ecosystem! +Now, let's create the `SkipClient` instance with the signers for each ecosystem! We are going to use Keplr for Cosmos transactions, MetaMask for EVM transactions, and Phantom for Solana transactions. @@ -90,9 +90,9 @@ const skipClient = new SkipClient({ ### 3\. Request a Quote -Now, we can use the `SkipClient.route` function to request a quote & route to swap USDC on Noble to TIA on Celestia: +Now, we can use the `SkipRouter.route` function to request a quote & route to swap USDC on Noble to TIA on Celestia: -Just add the following line after the line where you initialized the skipClient: +After initializing your `skipClient` add the following:: ```ts const route = await skipClient.route({ @@ -105,14 +105,15 @@ const route = await skipClient.route({ splitRoutes: true, }, }); + ``` - **Understanding the Route Response** + **Understanding the Route Response** -The route response contains a ton of information about how the user can move from their source chain & token to their destination. For more information, see [/v2/fungible/route](/api-reference/getroutev2) reference docs. + The route response contains a ton of information about how the user can move from their source chain & token to their destination. For more information, see [/v2/fungible/route](/api-reference/prod/fungible/post-v2fungibleroute) reference docs. -The most basic outputs you will need are: + The most basic outputs you will need are: - `amountOut`: The estimated amount your user will receive after their swap / transfer takes place -- net of fees (e.g. bridge fees, swap fees, etc..) and price impact. - `requiredChainAddresses`: These are the chainIDs for which you will need to pass a valid user address when generating the transaction. @@ -124,12 +125,12 @@ The most basic outputs you will need are: You can your set your own swap fee into the quote by setting `cumulativeAffiliateFeeBPS` to the total fee amount you want to collect from the user, measured in hundredths of a percent (aka "bips"). -You can find more info about setting fees in [Setting Affiliate Fees](/affiliate-fees) +You can find more info about setting fees in [Setting Affiliate Fees](/general/affiliate-fees) ### 5\. Get Required Addresses -Now that we have the route response, we can use our signer to get the list of chains where the user or reeceiver addresses are required for executing the route. +With the route response available, we can now use our signer to retrieve the list of chains where user or receiver addresses are required to execute the route. We'll use these addresses in the next step to populate `userAddresses` when executing the route with the `SkipClient.executeRoute` method. @@ -142,11 +143,11 @@ Funds could end up in any of the addresses you provide -- including intermediate See [Cross-chain Failure Cases](../advanced-transfer/handling-cross-chain-failure-cases) for more details on when funds might end up in an intermediate address. -(Rest assured that `SkipClient.transactionStatus` will tell you where your users funds end up even if they don't make it to their final destination.) +Rest assured that `SkipClient.transactionStatus` will tell you where your users funds end up even if they don't make it to their final destination. -It's recommended you keep the address somewhere and have function to get the address from the chainID. In this example we have a function called `getAddress` that takes the chainID and returns the address. +It's recommended you store the address(es) somewhere and have a function to get the address from the chainID. In this example we have a function called `getAddress` that takes the chainID and returns the address. Add the following snippet to your script after getting the route to retrieve the address associated with each `requiredChainAddresses` entry: @@ -162,17 +163,17 @@ const userAddresses = await Promise.all( ); ``` -Two things you should notice about this code: +Two things to note about this code: 1. The `userAddresses` array contains objects with `{chainID, address}` -2. The `userAddresses` array needs to have the same order and length as the `requiredChainAddresses` array had +2. The `userAddresses` array needs to have the same order and length as the `requiredChainAddresses` array in the route response **Never attempt to derive an address on one chain from an address on another chain** -Whenever you need a user address, please request it from the corresponding wallet / signer. Do not attempt to use bech32 cross-chain derivation. +Whenever you need a user address, please request it from the corresponding wallet or signer. Do not attempt to use bech32 cross-chain derivation. -If you attempt to derive an address on one chain from an address on another chain, you may derive an address that the user cannot actually sign for if the two chains have different address-derivation processes. For example, if you derive a Cosmos address from an Ethereum address, you will get an address that the user cannot sign for and cannot use. +If you attempt to derive an address on one chain from an address on another chain, you may derive an address that the user cannot actually sign for if the two chains have different address-derivation processes. For example, if you derive a Cosmos address from an Ethereum address, you will get an address that the user cannot sign for and thus risk lost tokens. @@ -197,13 +198,13 @@ await skipClient.executeRoute({ After the transaction completes, you'll have additional TIA in your Celestia address! - **`executeRoute` callbacks** + **`executeRoute` callbacks** -`executeRoute` takes care of all the complexity between getting a quote & executing a transaction: creating the tx, signing the tx, submitting it, and tracking it across all the chains. + `executeRoute` takes care of all the complexity between getting a quote & executing a transaction: creating the tx, signing the tx, submitting it, and tracking it across all the chains. -You can supply a variety of callbacks to hook into the process and update your UI or retrieve information while it's executing. + You can supply a variety of callbacks to hook into the process and update your UI or retrieve information while it's executing. -These callbacks include: + These callbacks include: - `onTransactionBroadcast(txInfo {txHash, chainID})`: Executes after the transaction that the user signs gets broadcast on chain. - `onTransactionTracked(txInfo, {txHash, chainID})`: Executes after the transaction that the user signs is successfully registered for tracking. diff --git a/docs/general/smart-relay.mdx b/docs/general/smart-relay.mdx index 7b531b32..27e53374 100644 --- a/docs/general/smart-relay.mdx +++ b/docs/general/smart-relay.mdx @@ -3,13 +3,13 @@ title: "Smart Relay" description: "This page covers Smart Relay -- Skip Go API's universal cross-chain data & token delivery service" --- -This document introduces Skip Go API’s Smart Relay functionality — the fastest & most reliable way to get your users where they’re going over any bridge Skip Go API supports. Smart Relay is an alternative to public bridge relayers, which we've designed to enable users to access more swap and transfer routes in fewer transactions more quickly & reliably. +This document introduces Skip Go API’s Smart Relay functionality — the fastest & most reliable way to get your users where they’re going over any bridge supported by Skip Go. Smart Relay is an alternative to public bridge relayers. It's designed to enable users to access more swap and transfer routes in fewer transactions with greater speed and reliability. **We strongly advise all integrators who want to offer top-notch user experiences to activate Smart Relay.** - **If you do not use Smart Relay, you will suffer worse performance in a variety of ways:** + **If you do not use Smart Relay, your performance will suffer:** * Many routes will not be available (e.g. Bridging Solana to Base, Solana to any Cosmos chain) * Many routes will require more transactions (e.g. Bridging USDC from Ethereum to Osmosis will require 2 transactions, instead of 1) @@ -38,16 +38,16 @@ This document covers: Smart Relay is a **intent-aware**, **user-centric**, **universal** relayer with better performance guarantees than public relayers for all bridges and routes we support. We offer it at a small cost to the end-user and no cost to the developer/integrator. In short, Smart Relay helps users get to more destinations, in fewer transactions, and at faster speeds than via public relayers — no matter how many bridges or chains stand between them and their destination. -Smart Relay is huge improvement over existing relaying systems, made possible by intelligent integration with Skip Go API's routing capabilities.: +Smart Relay is huge improvement over existing relaying systems, made possible by intelligent integration with Skip Go's routing capabilities.: -* **Intent-aware**: Traditional relayers are unaware of what the user is trying to accomplish beyond performing 1 single hop of a transfer, but usually transfers are a part of a broader sequence of swaps, transfers, and actions. Smart Relayer has the context of the user's end-to-end cross-chain intent, and it can use information to optimize its execution plan. +* **Intent-aware**: Traditional relayers are unaware of what the user is trying to accomplish beyond the first hop of a transfer, but usually transfers are a part of a broader sequence of swaps, transfers, and actions. Smart Relayer has the context of the user's end-to-end cross-chain intent, and it can use this information to optimize its execution plan. * For example, Smart Relay can reduce the number of transactions a user must sign in a route by automatically triggering the second bridge in a route when delivering the packet for the first bridge (e.g. Triggering IBC from CCTP). * It can also use this information to prepare the user's destination address to receive the transfer (e.g. Dust it with gas even if there's no way to perform an atomic swap, or initialize a token account on Solana, etc...). -* **User-centric**: Traditional relayers are "channel" or "bridge" centric. They just try to move all of the packets for a single route of a bridge from one chain to another, then they view their job as done. Smart Relayer is built around users, not bridges. This means that it instead of moving all of the packets in 1 bridge until that bridge is cleared, it moves all of the packets for 1 user across multiple bridges/hops -- until that user reaches their destination. - * It also offers a deeply simplified payment experience for users thats designed for multi-hop: pay once in the source chain, in the token you're transferring, and receive high quality relaying at every leg of the route after. -* **Universal**: Traditional relayers support 1 or 2 chains or ecosystems at a time for a single bridge. Cross-ecosystem transfers are fraught as a result. Many routes have no relayers or just spotty coverage. Smart Relay was designed to support all ecosystems and all bridges from the start. It already supports EVM, Solana/SVM, Cosmos, and modular -- with more chains, bridges, and routes coming shortly. +* **User-centric**: Traditional relayers are focused on specific "channels" or "bridges," simply transferring all packets for a single bridge route from one chain to another. Once that task is complete, they consider their job done. In contrast, Smart Relayers prioritize the user, not the bridge. Instead of clearing packets on one bridge at a time, they transfer all packets associated with a specific user across multiple bridges or hops, ensuring the user reaches their destination efficiently. + * It also offers a deeply simplified payment experience for users that's designed for multi-hop: pay once in the source chain, in the token you're transferring, and receive high quality relaying at every leg of the route thereafter. +* **Universal**: Traditional relayers only support 1 or 2 chains or ecosystems at a time for a single bridge, making cross-ecosystem transfers fraught. Many routes have no relayers or just spotty coverage. Smart Relay was designed to support all ecosystems and all bridges from the start. It already supports EVM, Solana/SVM, Cosmos, and modular -- with more chains, bridges, and routes routinely added. -The cost of Smart Relay is determined dynamically based on several factors covered below gas prices on every chain and bridge fees involved in the route. +The cost of Smart Relay is determined dynamically based on the factors covered below. The gas prices and bridge fees involved in a route are the principal determinants of that cost. ## State of Smart Relay @@ -61,7 +61,7 @@ We are currently building out support for: * Hyperlane * Axelar -For the bridges that Smart Relay does not support today, Skip Go API uses public or enshrined relayers — at whatever cost they’re typically made available to users. (These are free for IBC and have some fee associated with them for others). All costs users will incur will always be made transparent in the relevant endpoint responses. +For the bridges that Smart Relay does not support today, Skip Go uses public or enshrined relayers — at whatever cost they’re typically made available to users. (These are free for IBC and have some fee associated with them for others). All costs users will incur will always be made transparent in the relevant endpoint responses. ## How to Use Smart Relay @@ -70,36 +70,36 @@ For the bridges that Smart Relay does not support today, Skip Go API uses public 1. On `/route` or `/msgs_direct`, pass `smart_relay=true` 2. If using `/msgs`, ensure that you are passing the `smart_relay_fee_quote` object provided in the `cctp_transfer` operation from the `/route` response into your `/msgs` request. - If you're using the @skip-go/client library, version 0.8.0 and above supports this automatically. If you're integrating the API directly and decoding the `/route` response operations before passing them back into `msgs`, simply ensure you're decoding this new field properly and passing it back through! -3. Sign the transaction as usual, and submit the signed transaction to Skip Go API via `/track` or `/submit` as normal - - **NOTE: We HIGHLY recommend using `/submit` to submit Smart Relay transactions on chain to avoid any errors with submitting a transaction on chain but not sending to the `/track` endpoint.** +3. Sign the transaction as usual, and submit the signed transaction to the Skip Go API via `/track` or `/submit` as normal + - **NOTE: We HIGHLY recommend using `/submit` to submit Smart Relay transactions on chain to avoid issues incurred by submitting a transaction on chain but not sending it to the `/track` endpoint.** That’s it! Smart Relay will take care of executing your cross-chain actions across all bridges it currently supports. ### How to determine what Smart Relay will cost the user -In the response to `/route` , `/msgs_direct` and `/msgs`, the cost of Smart Relay will appear in the `estimated_fees` array with `fee_type` set to `SMART_RELAY`. See [Getting Fees](/fe-info) for more info about `estimated_fees` +In the response to `/route` , `/msgs_direct` and `/msgs`, the cost of Smart Relay will appear in the `estimated_fees` array with `fee_type` set to `SMART_RELAY`. See [Getting Fee Info](./fee-info) for more info about `estimated_fees` For multi-tx routes, the user may pay up to 1 Smart Relay fee per transaction. -The fee for each transaction pays for all Smart Relay operations in that particular transaction. This prevents Smart Relay from accepting payment prematurely to perform operations for the latter transactions, since the latter transactions might not get signed / executed. +The fee for each transaction pays for all Smart Relay operations in that particular transaction. This prevents Smart Relay from accepting payment prematurely to perform operations for the latter transactions, since the latter transactions may not get signed or executed. You can use the `tx_index` attribute on the `estimated_fees` entries to identify which Smart Relay fee corresponds to which transaction in the route. (e.g. `tx_index=0` indicates this is the fee for the first transaction in the route) ### What Determines the Cost of Smart Relaying -Smart Relay incurs a user cost because Smart Relay involves actually submitting transactions to various chains and incurring transaction fee costs as a result. +Smart Relay incurs a user cost because Smart Relay involves actually submitting transactions to various chains and incurring transaction fees as a result. -* **Operations**: The cost of relaying a route depends on the operations in the route, since these affect the amount of gas Smart Relay consumes (e.g. Routes that include swaps will require higher gas amounts & involve more expensive relaying) -* **The cost of gas:** Most networks have dynamic fee markets, where the price of gas increases during times of high network load. Smart Relay takes this into account when generating a quote +* **Operations**: The cost of relaying a route depends on the operations in the route, since these affect the amount of gas Smart Relay consumes (e.g. routes that include swaps will require higher gas amounts & involve more expensive relaying) +* **The cost of gas:** Most networks have dynamic fee markets, where the price of gas increases during periods of high network load. Smart Relay takes this into account when generating a quote * **Token Exchange Rates:** The token the user pays their fee in and the token Smart Relaying pays gas fees in may differ, so exchange rates affect the price the end user experiences. (e.g. If the user pays in OSMO for a route that terminates on Ethereum mainnet, Smart Relay will need to pay fees in ETH, so the amount of OSMO the user pays will depend on the OSMO/ETH spot price.) ### How to properly use the Smart Relay Fee Quote -Skip Go API dynamically calculates the Smart Relay fee to be paid based on the underlying costs in real-time. +Skip Go dynamically calculates the Smart Relay fee to be paid based on the underlying costs in real-time. -Although you should use the information in the `estimated_fees` array for display purposes, a new `smart_relay_fee_quote` object has been added to the `cctp_transfer`, providing necessary information for proper use of the dynamic relaying fee system. Specifically, the `smart_relay_fee_quote` object contains information about the smart relay fee to be paid and when the quote expires (after which the quoted amount may no longer be valid and the transaction may not be succesfully relayed). +Although you should use the information in the `estimated_fees` array for display purposes, `cctp_transfer` includes a `smart_relay_fee_quote`, providing necessary information for proper use of the dynamic relaying fee system. Specifically, the `smart_relay_fee_quote` object contains information about the smart relay fee to be paid and when the quote expires (after which the quoted amount may no longer be valid and the transaction may not be succesfully relayed). -If you're using the `/msgs` endpoint, ensure that you are passing the `smart_relay_fee_quote` object provided in the `cctp_transfer` operation from the `/route` response into your `/msgs` request. This is necessary to ensure the transaction generated by the API matches the fee quoted in the `/route` request. If the quote is not passed back into the `/msgs` request, a new quote will be generated in the `/msgs` call that may be different than what was quoted previously in the `/route` request. Version `0.8.0` and above of the `@skip-go/client` library supports this automatically. If you're integrating the API directly and decoding the `/route` response operations before passing them back into `/msgs`, simply ensure you're decoding this new field properly and passing it back through! If you don't pass the The new object's fields are provided below: +If you're using the `/msgs` endpoint, ensure that you are passing the `smart_relay_fee_quote` object provided in the `cctp_transfer` operation from the `/route` response into your `/msgs` request. This is necessary to ensure the transaction generated by the API matches the fee quoted in the `/route` request. If the quote is not passed back into the `/msgs` request, a new quote will be generated in the `/msgs` call that may be different than what was quoted previously in the `/route` request. Version `0.8.0` and above of the `@skip-go/client` library supports this automatically. If you're integrating the API directly and decoding the `/route` response operations before passing them back into `/msgs`, simply ensure you're decoding this new field properly and passing it back through! See the `SmartRelayFeeQuote` below: @@ -131,4 +131,4 @@ export type SmartRelayFeeQuote = { **Want to help us get better? Have questions or feedback?** You can reach us easily by joining [our Discord](https://skip.build/discord) and grabbing the "Skip Go Developer" role. - \ No newline at end of file + diff --git a/docs/general/supported-ecosystems-and-bridges.mdx b/docs/general/supported-ecosystems-and-bridges.mdx index de8be887..1d9112c2 100644 --- a/docs/general/supported-ecosystems-and-bridges.mdx +++ b/docs/general/supported-ecosystems-and-bridges.mdx @@ -6,9 +6,9 @@ title: "Supported Ecosystems" **Activate Smart Relay (`smart_relay=true`) for global coverage of all chains, bridges, and routes** - There are many routes that will return a RouteNotFound error if `smart_relay=false` because there are not public relayers that support them. This includes all routes to and from Solana, as well as CCTP routes to & from Polygon, Base, and several other L2s. + There are many routes that will return a RouteNotFound error if `smart_relay=false` because there are not public relayers that support them. This includes all routes to and from Solana, as well as CCTP routes to and from Polygon, Base, and several other L2s. - As a result, if you want your users to be able to transfer their tokens over all routes, we recommend using Smart Relay. You can read more about Smart Relay here: [Smart Relay](/smart-relay) + As a result, if you want your users to be able to transfer their tokens over all routes, we recommend using [Smart Relay](/general/smart-relay). Skip Go API is a universal interoperability platform. It can be used to swap and transfer tokens within and between all major ecosystems in crypto over many major bridges. We're constantly adding new bridges, new chains, new routes on already-supported bridges, and new multi-hop routes by composing multiple bridges together. @@ -46,11 +46,11 @@ The very short summary is that our Cosmos ecosystem support is most mature, foll - **Never attempt to derive Cosmos Addresses from Ethereum Addresses (or Vice Versa)** + **Never attempt to derive Cosmos Addresses from Ethereum Addresses (or vice versa)** Whenever you need an address on a chain for a user, please request it from the corresponding wallet. - If you attempt to derive an address on one chain from an address on another chain, you may derive an address that the user cannot actually sign for if the two chains have different address-derivation processes. For example, if you derive a Cosmos address from an Ethereum address, you will get an address that the user cannot sign for and cannot use. + If you attempt to derive an address on one chain from an address on another chain, you may derive an address that the user cannot actually sign for if the two chains have different address-derivation processes. For example, if you derive a Cosmos address from an Ethereum address, you will get an address that the user cannot sign for or use. So don't ever try to derive one address from another -- even for intermediate addresses. (Intermediate addresses may be used for fund recovery if there is some kind of failure on an intermediate chain. Failures could include a timeout, a swap exceeding slippage tolerance, or any other unexpected execution path. We assume users can sign for intermediate addresses, even if they shouldn't have to.) diff --git a/docs/mint.json b/docs/mint.json index a2c824d3..ead1f6f3 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -50,7 +50,7 @@ "general/smart-relay", "general/post-route-actions", "general/affiliate-fees", - "general/fe-info", + "general/fee-info", "general/faq", "general/upcoming-features" ] diff --git a/docs/swagger.yml b/docs/swagger.yml index 21be4c60..f05538b9 100644 --- a/docs/swagger.yml +++ b/docs/swagger.yml @@ -1543,7 +1543,7 @@ paths: application/json: example: code: 5 - message: chain id not supported + message: chain ID not supported details: [] schema: $ref: '#/components/schemas/Error' @@ -1611,7 +1611,7 @@ paths: application/json: example: code: 5 - message: chain id not supported + message: chain ID not supported details: [] schema: $ref: '#/components/schemas/Error' diff --git a/docs/widget/configuration-options.mdx b/docs/widget/configuration-options.mdx index 18247f35..856f6785 100644 --- a/docs/widget/configuration-options.mdx +++ b/docs/widget/configuration-options.mdx @@ -130,7 +130,7 @@ interface SwapWidgetProps { ### `defaultRoute` -`defaultRoute` allows you to customize the first route that appears on the widget on page load. Use this to direct your users to the most important route you expect them to be interested in when they arrive to your dApp. [JEREMY TODO: Show them how to use the API to get the defaultRoute params (chain id, denoms)] +`defaultRoute` allows you to customize the first route that appears on the widget on page load. Use this to direct your users to the most important route you expect them to be interested in when they arrive to your dApp. [JEREMY TODO: Show them how to use the API to get the defaultRoute params (chain ID, denoms)] - `amountIn` (number): The amount in to be preset on the default route, resulting in a swap/transfer/bridge exact amount in request. - `amountOut` (number): The amount out to be preset on the default route, resulting in a swap/transfer/bridge exact amount out request. If both `amountIn` and `amountOut` are specified, only the `amountIn` will be used, as you cannot specify both an exact amount in and exact amount out.