docs: restructure top-level readme (#35)

* docs: restructure top-level readme * docs: add basic example to top-level
across-protocol · Oct 4, 2024 · 925ec2a · 925ec2a
1 parent 790c7b9
commit 925ec2a
Show file tree

Hide file tree

Showing 2 changed files with 165 additions and 65 deletions.
diff --git a/README.md b/README.md
@@ -3,69 +3,54 @@
 <p align="center">
   <a href="https://across.to">
       <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="./.github/across-logo-dark.png">
-        <img alt="across logo" src="./.github/across-logo-light.png" width="auto" height="60">
+        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/across-protocol/toolkit/refs/heads/master/.github/across-logo-dark.png">
+        <img alt="across logo" src="https://raw.githubusercontent.com/across-protocol/toolkit/refs/heads/master/.github/across-logo-light.png" width="auto" height="60">
       </picture>
 </a>
 </p>
 
 <p align="center">
-  Toolkit for building on top of the <a href="https://across.to">Across Protocol</a> 🛠️ 
+  Toolkit  🛠️ for building on top of the <a href="https://across.to">Across Protocol</a> 
 <p>
+<p align="center">
+  Fastest and lowest-cost bridging for end-users. Streamlined interoperability for developers.
+</p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@across-protocol/integrator-sdk">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/@across-protocol/integrator-sdk?colorA=21262d&colorB=21262d&style=flat">
-      <img src="https://img.shields.io/npm/v/@across-protocol/integrator-sdk?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="Version">
-    </picture>
+  <a href="https://discord.across.to" target="_blank" rel="noreferrer">
+    <img src="https://img.shields.io/badge/Chat%20on-Discord-%235766f2" />
   </a>
-  <a href="https://github.com//@across-protocol/integrator/blob/master/LICENSE">
+  <a href="https://github.com/across-protocol/toolkit/blob/master/LICENSE">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/license-AGPL-21262d?style=flat">
       <img src="https://img.shields.io/badge/license-AGPL-f6f8fa?style=flat" alt="MIT License">
     </picture>
   </a>
+  <a href="https://twitter.com/AcrossProtocol/" target="_blank" rel="noreferrer">
+    <img src="https://img.shields.io/twitter/follow/AcrossProtocol?style=social"/>
+  </a>
 </p>
 
 <br>
 
-# 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
+## Overview
 
-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.
+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: "YOUR_INTEGRATOR_ID",
+  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
+// 2. Retrieve quote for USDC from Optimism -> Arbitrum
 const route = {
   originChainId: optimism.chainId
   destinationChainId: arbitrum.chainId,
@@ -76,46 +61,33 @@ 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();
 
+// 3. Execute quote
 await client.executeQuote({
   walletClient: wallet,
-  deposit: quote.deposit, // returned by `getQuote`
+  deposit: quote.deposit,
   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: <https://across.to>
+- App: <https://app.across.to>
+- Docs: <https://docs.across.to>
+- Medium: <https://medium.com/across-protocol>
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
@@ -1,5 +1,133 @@
+<br/>
+
+<p align="center">
+  <a href="https://across.to">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/across-protocol/toolkit/refs/heads/master/.github/across-logo-dark.png">
+        <img alt="across logo" src="https://raw.githubusercontent.com/across-protocol/toolkit/refs/heads/master/.github/across-logo-light.png" width="auto" height="60">
+      </picture>
+</a>
+</p>
+
+<p align="center">
+  TypeScript package for building on top of the <a href="https://across.to">Across Protocol</a>
+<p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@across-protocol/integrator-sdk">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/@across-protocol/integrator-sdk?colorA=21262d&colorB=21262d&style=flat">
+      <img src="https://img.shields.io/npm/v/@across-protocol/integrator-sdk?colorA=f6f8fa&colorB=f6f8fa&style=flat" alt="Version">
+    </picture>
+  </a>
+  <a href="https://github.com/across-protocol/toolkit/blob/master/LICENSE">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/license-AGPL-21262d?style=flat">
+      <img src="https://img.shields.io/badge/license-AGPL-f6f8fa?style=flat" alt="MIT License">
+    </picture>
+  </a>
+</p>
+
+<br>
+
+# 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