From fa14652a96e14099ca24ef74352205ffcb6dd95f Mon Sep 17 00:00:00 2001 From: Dong-Ha Kim Date: Wed, 2 Oct 2024 16:56:40 +0200 Subject: [PATCH 1/2] docs: restructure top-level readme --- README.md | 119 +++++++++---------------------------- packages/sdk/README.md | 130 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 155 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index bd57de1..799fb82 100644 --- a/README.md +++ b/README.md @@ -3,119 +3,52 @@

- - across logo + + across logo

- Toolkit for building on top of the Across Protocol 🛠️ + Toolkit 🛠️ for building on top of the Across Protocol

+

+ Fastest and lowest-cost bridging for end-users. Streamlined interoperability for developers. +

- - - - Version - + + - + MIT License + + +


-# Getting Started - -The `@across-protocol/integrator-sdk` provides useful abstractions on top of Across' Smart Contracts and Quotes API. - -To learn more visit our [docs](https://docs.across.to/). - -## Installation - -To get started, install the integrator sdk and its peer dependency [viem](https://viem.sh/). - -```bash -pnpm i @across-protocol/integrator-sdk viem -``` - -## Quick Start - -### 1. Set up the `AcrossClient` - -Firstly, you need to set up the `AcrossClient` and configure the chains you want to support. - -```ts -import { createAcrossClient } from "@across-protocol/integrator-sdk"; -import { mainnet, optimism, arbitrum } from "viem/chains"; - -const client = createAcrossClient({ - integratorId: "YOUR_INTEGRATOR_ID", - chains: [mainnet, optimism, arbitrum], -}); -``` - -### 2. Retrieve a quote - -Now, you can retrieve a quote for a given route. - -```ts -// USDC from Optimism -> Arbitrum -const route = { - originChainId: optimism.chainId - destinationChainId: arbitrum.chainId, - inputToken: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", - outputToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", -}; -const quote = await client.getQuote({ - route, - inputAmount: parseUnit("1000", 6) // USDC decimals -}) -``` - -Note that we provide additional utilities for retrieving available routes, chain details, and token infos. -See [SDK reference](./packages/sdk/README.md). - -### 3. Execute a quote - -After retrieving a quote, you are ready to execute it. - -```ts -import { useWalletClient } from "wagmi"; - -const wallet = useWalletClient(); - -await client.executeQuote({ - walletClient: wallet, - deposit: quote.deposit, // returned by `getQuote` - onProgress: (progress) => { - // handle progress - }, -}); -``` - -The method will execute a quote by: - -1. Approving the SpokePool contract if necessary -2. Depositing the input token on the origin chain -3. Waiting for the deposit to be filled on the destination chain - -You can use the `onProgress` callback to act on different stages of the execution. -Have a look at our [example app](./apps/example/) for a more detailed usage of this method. - -## Cross-chain message handling +## Tools -TODO +| Package | Description | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| [`@across-protocol/integrator-sdk`](./packages/sdk/README.md) | TypeScript package for building on top of Across Protocol's Smart Contracts and Quotes API | -## Error handling and debugging +## Examples -TODO +| App | Description | +| ---------------------------------- | ------------------------------------ | +| [using viem](./apps/example/app) | Example Next.js app using [viem]() | +| [using ethers](./apps/example/app) | Example Next.js app using [ethers]() | -## Route, chain and token details +## Links -TODO +- Website: +- App: +- Docs: +- Medium: diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 1614c96..11ab65b 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -1,5 +1,133 @@ +
+ +

+ + + + across logo + + +

+ +

+ TypeScript package for building on top of the Across Protocol +

+ +

+ + + + Version + + + + + + MIT License + + +

+ +
+ +# Getting Started + +The `@across-protocol/integrator-sdk` provides useful abstractions on top of Across' Smart Contracts and Quotes API. + +To learn more visit our [docs](https://docs.across.to/). + +## Installation + +To get started, install the integrator sdk and its peer dependency [viem](https://viem.sh/). + +```bash +pnpm i @across-protocol/integrator-sdk viem +``` + +## Quick Start + +### 1. Set up the `AcrossClient` + +Firstly, you need to set up the `AcrossClient` and configure the chains you want to support. + +```ts +import { createAcrossClient } from "@across-protocol/integrator-sdk"; +import { mainnet, optimism, arbitrum } from "viem/chains"; + +const client = createAcrossClient({ + integratorId: "0xdead", // 2-byte hex string + chains: [mainnet, optimism, arbitrum], +}); +``` + +### 2. Retrieve a quote + +Now, you can retrieve a quote for a given route. + +```ts +// USDC from Optimism -> Arbitrum +const route = { + originChainId: optimism.chainId + destinationChainId: arbitrum.chainId, + inputToken: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", + outputToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", +}; +const quote = await client.getQuote({ + route, + inputAmount: parseUnit("1000", 6) // USDC decimals +}) +``` + +Note that we provide additional utilities for retrieving available routes, chain details, and token infos. +See [here](#chains-and-routes). + +### 3. Execute a quote + +After retrieving a quote, you are ready to execute it. + +```ts +import { useWalletClient } from "wagmi"; + +const wallet = useWalletClient(); + +await client.executeQuote({ + walletClient: wallet, + deposit: quote.deposit, // returned by `getQuote` + onProgress: (progress) => { + // handle progress + }, +}); +``` + +The method will execute a quote by: + +1. Approving the SpokePool contract if necessary +2. Depositing the input token on the origin chain +3. Waiting for the deposit to be filled on the destination chain + +You can use the `onProgress` callback to act on different stages of the execution. +Have a look at our [example app](../../apps/example) for a more detailed usage of this method. + +## Deposit details + +TODO + +## Cross-chain message handling + +TODO + +## Error handling and debugging + +TODO + +## Route, chain and token details + +TODO + # `@across-protocol/integrator-sdk` Reference +For the full detailed reference see [here](./docs/README.md). + ## `AcrossClient` ### Set Up @@ -10,7 +138,7 @@ ### Chains and Routes - [`getSupportedChains`](./docs/classes/AcrossClient.md#getsupportedchains) -- [`getAvailableRoutes`](./docs/classes/AcrossClient.md#getquote) +- [`getAvailableRoutes`](./docs/classes/AcrossClient.md#getavailableroutes) ### Quotes, Fees and Limits From 31ee1d79af259b3582d7cb5ab0c66b05a509ea33 Mon Sep 17 00:00:00 2001 From: Dong-Ha Kim Date: Wed, 2 Oct 2024 17:20:11 +0200 Subject: [PATCH 2/2] docs: add basic example to top-level --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index 799fb82..574d328 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,45 @@
+## Overview + +Quickly integrate with a few lines of code. See [here](./packages/sdk/README.md) for more details. + +```ts +import { createAcrossClient } from "@across-protocol/integrator-sdk"; +import { mainnet, optimism, arbitrum } from "viem/chains"; +import { useWalletClient } from "wagmi"; + +const wallet = useWalletClient(); + +// 1. Create client +const client = createAcrossClient({ + integratorId: "0xdead", // 2-byte hex string + chains: [mainnet, optimism, arbitrum], +}); + +// 2. Retrieve quote for USDC from Optimism -> Arbitrum +const route = { + originChainId: optimism.chainId + destinationChainId: arbitrum.chainId, + inputToken: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", + outputToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", +}; +const quote = await client.getQuote({ + route, + inputAmount: parseUnit("1000", 6) // USDC decimals +}) + +// 3. Execute quote +await client.executeQuote({ + walletClient: wallet, + deposit: quote.deposit, + onProgress: (progress) => { + // handle progress + }, +}); +``` + ## Tools | Package | Description |