Updated SDK V3 Guides (#524)

Co-authored-by: dannydaniil <danny.daniil@uniswap.org>

.eslintrc.json

@@ -9,7 +9,8 @@
         "plugin:@typescript-eslint/recommended",
         "plugin:react-hooks/recommended",
         "prettier/@typescript-eslint",
-        "plugin:prettier/recommended"
+        "plugin:prettier/recommended",
+        "plugin:markdown/recommended"
     ],
     "overrides": [],
     "parserOptions": {

docs/sdk/v3/guides/01-background.md

@@ -0,0 +1,68 @@
+---
+id: background
+title: Background
+---
+
+Before integrating with Uniswap, it may be helpful for newcomers to review the following background information on some important developer web3 concepts, the structure of our examples, and SDK concepts.
+
+:::info
+Already familiar with web3 development and/or the basics of our SDK and want to get right to the code? Start with our first guide, [Getting a Quote](./02-quoting.md)!
+:::
+
+## Providers
+
+Communication with the blockchain is typically done through a provider and local models of smart contracts and their [ABIs](./01-background.md#abis).
+
+To achieve this, our examples use the [ethers.js](https://docs.ethers.io/v5/) library. To instantiate a provider you will need a data source. Our examples offer two options:
+
+- **JSON RPC URL**: If you are working directly with the Ethereum mainnet or a local fork, products such as [infura](https://infura.io/) offer JSON RPC URLs for a wide variety of chains and testnets. For our examples, we'll only be using the Ethereum mainnet.
+
+- **Wallet Extension**: If you are connecting to a wallet browser extension, these wallets embed a source directly into the Javascript window object as `window.ethereum`. This object surfaces information about the user's wallets and provides the ability to communicate with the connected chain. Importantly for our examples, it can be used with `ethers.js` to construct a provider.
+
+## Uniswap's Runnable Examples
+
+Each guide is accompanied and driven by [runnable examples](https://github.com/Uniswap/examples/tree/main/v3-sdk) using React to provide a basic UI for interacting with the example. Each examples provides relevant options such as running against a local blockchain or connecting to the Ethereum mainnet directly. You also have the option of using a wallet extension which can be connected to either environment.
+
+Inputs and environment settings are configured in each example's `config.ts` and allows for simple setup and configuration.
+
+### Developing and Testing
+
+To test your code, we recommend utilizing a local fork of the Ethereum mainnet. To help facilitate easy testing, each example includes a quickstart for running the local chain with a test wallet. To further test, we also recommend using a wallet extension and connecting to the local chain. Finally, each example can be run against the Ethereum mainnet if desired. Full development instructs can be found in the `README.md` of each code example.
+
+### Utility Libraries
+
+Each example is concentrated into a single file within the `libs/` folder of the example, with the entry points noted in each guide and README.
+
+To allow the guides to focus on the SDK's core functionality, additional basic building blocks can be found in each example's `libs` folder. The exported functionality from these files is intended to be the minimum needed for each example and not a complete library for production usage. These also include storing core constants such as definitions for tokens, ABI's, and blockchain addresses that can distract from the core concepts. Below are summaries of the helping libraries you will encounter.
+
+#### Provider Utilities
+
+`provider.ts` wraps the basics of `ethers.js` and connecting to wallet extensions into an abstracted view of a provider, a wallet address, and the ability to send transactions. It also helps abstract the configured environment you wish to run against in your example without making code changes outside of your configuration.
+
+#### Wallet Utilities
+
+`wallet.ts` offers the ability to query a wallet (whether connected via an extension or defined in code/config) for its balances and other essential information.
+
+#### Pool Infroamtion
+
+`pool.ts` contains the basic querying of pool information when not essential / core to the relevant guide
+
+#### Display Utilities
+
+`conversion.ts` provides display and light math wrappers to help show human readable prices when dealing with currency amounts (typically stored as raw numbers and the decimal placement separate for precision reasons) in the form of two functions: `fromReadableAmount` and `toReadableAmount`
+
+## Notable SDK Structures and Concepts
+
+When working with the SDK it can be helpful to understand some of the design choices and why they are needed. Below you can find a few important concepts.
+
+### ABI's
+
+To allow others to interact with a smart contract, each contract exposes an ABI (Application Binary Interface). As these are defined on the blockchain, we must ensure the correct definitions are provided to our Javascript functions. ABI's are provided from various SDK's and imported in as needed. Some examples will define an ABI directly as needed.
+
+### CurrencyAmount and JSBI
+
+Cryptocurrency applications often work with very small fractions of tokens. As a result, high precision is very important. To ensure precision is upheld, the `CurrencyAmount` class helps store exact values as fractions and utilizes [JSBI](https://github.com/GoogleChromeLabs/jsbi) for compatibility across the web. To display these amounts nicely to users, additional work is sometimes required.
+
+### Currency
+
+The `Currency` class can represent both native currency (ETH) and an ERC20 `Token`. Currencies vary in their relative value, so the `Token` class allows your application to define the number of decimals needed for each currency along with the currency's address, symbol, and name.

docs/sdk/v3/guides/02-quoting.md

@@ -0,0 +1,115 @@
+---
+id: quoting
+title: Getting a Quote
+---     
+
+## Introduction
+
+This guide will cover how to get the current quotes for any token pair on the Uniswap protocol. It is based on the [Quoting code example](https://github.com/Uniswap/examples/tree/main/v3-sdk/quoting), found in the Uniswap code examples [repository](https://github.com/Uniswap/examples). To run this example, check out the examples's [README](https://github.com/Uniswap/examples/blob/main/v3-sdk/minting-position/README.md) and follow the setup instructions.
+
+:::info
+If you need a briefer on the SDK and to learn more about how these guides connect to the examples repository, please visit our [background](./01-background.md) page!
+:::
+
+In this example we will use `quoteExactInputSingle` to get a quote for the pair **USDC - WETH**.
+The inputs are the **token in**, the **token out**, the **amount in** and the **fee**.
+
+The **fee** input parameters represents the swap fee that distributed to all in range liquidity at the time of the swap. It is one of the identifiers of a Pool, the others being **tokenIn** and **tokenOut**.
+
+The guide will **cover**:
+
+1. Computing the Pool's deployment address
+2. Referencing the Pool contract and fetching metadata
+3. Referencing the Quoter contract and getting a quote
+
+At the end of the guide, we should be able to fetch a quote for the given input token pair and the input token amount with the press of a button on the web application.
+
+For this guide, the following Uniswap packages are used:
+
+- [`@uniswap/v3-sdk`](https://www.npmjs.com/package/@uniswap/v3-sdk)
+- [`@uniswap/sdk-core`](https://www.npmjs.com/package/@uniswap/sdk-core)
+
+The core code of this guide can be found in [`quote.ts`](https://github.com/Uniswap/examples/blob/main/v3-sdk/quoting/src/libs/quote.ts)
+
+## Computing the Pool's deployment address
+
+To interact with the **USDC - WETH** Pool contract, we first need to compute its deployment address.
+The SDK provides a utility method for that:
+
+```typescript reference title="Computing the Pool's address" referenceLinkText="View on Github" customStyling
+https://github.com/Uniswap/examples/blob/b5e64e3d6c17cb91bc081f1ed17581bbf22024bc/v3-sdk/quoting/src/libs/quote.ts#L40-L45
+```
+
+Since each *Uniswap V3 Pool* is uniquely identified by 3 characteristics (token in, token out, fee), we use those
+in combination with the address of the *PoolFactory* contract to compute the address of the **USDC - ETH** Pool.
+These parameters have already been defined in our configuration file:
+
+```typescript reference title="Configuration Parameters" referenceLinkText="View on Github" customStyling
+https://github.com/Uniswap/examples/blob/1ef393c2b8f8206a3dc5a42562382c267bcc361b/v3-sdk/quoting/src/config.ts#L34-L39
+```
+
+## Referencing the Pool contract and fetching metadata
+
+Now that we have the deployment address of the **USDC - ETH** Pool, we can construct an instance of an **ethers** `Contract` to interact with it:
+
+```typescript reference title="Setting up a reference to the Pool contract" referenceLinkText="View on Github" customStyling
+https://github.com/Uniswap/examples/blob/b5e64e3d6c17cb91bc081f1ed17581bbf22024bc/v3-sdk/quoting/src/libs/quote.ts#L47-L51
+```
+
+To construct the *Contract* we need to provide the address of the contract, its ABI and the provider that will carry out the RPC call for us.
+We get access to the contract's ABI through the [@uniswap/v3-core](https://www.npmjs.com/package/@uniswap/v3-core) package, which holds the core smart contracts of the Uniswap V3 protocol:
+
+```typescript reference title="Uniswap V3 Pool smart contract ABI" referenceLinkText="View on Github" customStyling
+https://github.com/Uniswap/examples/blob/b5e64e3d6c17cb91bc081f1ed17581bbf22024bc/v3-sdk/quoting/src/libs/quote.ts#L5
+```
+
+Having constructed our reference to the contract, we can now access its methods through our provider.
+We use a batch `Promise` call. This approach queries state data concurrently, rather than sequentially, to avoid out of sync data that may be returned if sequential queries are executed over the span of two blocks:
+
+```typescript reference title="Getting Pool metadata from the Pool smart contact" referenceLinkText="View on Github" customStyling
+https://github.com/Uniswap/examples/blob/b5e64e3d6c17cb91bc081f1ed17581bbf22024bc/v3-sdk/quoting/src/libs/quote.ts#L52-L56
+```
+
+The return values of these methods will become inputs to the quote fetching function.
+
+:::note
+In this example, the metadata we fetch is already present in our inputs. This guide fetches this information first in order to show how to fetch any metadata, which will be expanded on in future guides.
+:::
+
+## Referencing the Quoter contract and getting a quote
+
+Like we did for the Pool contract, we need to construct an instance of an **ethers** `Contract` for our Quoter contract in order to interact with it:
+
+```typescript reference title="Setting up a reference to the Quoter contract" referenceLinkText="View on Github" customStyling
+https://github.com/Uniswap/examples/blob/b5e64e3d6c17cb91bc081f1ed17581bbf22024bc/v3-sdk/quoting/src/libs/quote.ts#L14-L18
+```
+
+We get access to the contract's ABI through the [@uniswap/v3-periphery](https://www.npmjs.com/package/@uniswap/v3-periphery) package, which holds the periphery smart contracts of the Uniswap V3 protocol:
+
+```typescript reference title="Uniswap V3 Quoter smart contract ABI" referenceLinkText="View on Github" customStyling
+https://github.com/Uniswap/examples/blob/b5e64e3d6c17cb91bc081f1ed17581bbf22024bc/v3-sdk/quoting/src/libs/quote.ts#L4
+```
+
+We can now use our Quoter contact to obtain the quote.
+
+In an ideal world, the quoter functions would be `view` functions, which would make them very easy to query on-chain with minimal gas costs. However, the Uniswap V3 Quoter contracts rely on state-changing calls designed to be reverted to return the desired data. This means calling the quoter will be very expensive and should not be called on-chain.
+
+To get around this difficulty, we can use the `callStatic` method provided by the **ethers.js** `Contract` instances.
+This is a useful method that submits a state-changing transaction to an Ethereum node, but asks the node to simulate the state change, rather than to execute it. Our script can then return the result of the simulated state change:
+
+```typescript reference title="Getting Quotes from the Quoter contract" referenceLinkText="View on Github" customStyling
+https://github.com/Uniswap/examples/blob/b5e64e3d6c17cb91bc081f1ed17581bbf22024bc/v3-sdk/quoting/src/libs/quote.ts#L21-L30
+```
+
+The result of the call is the number of output tokens you'd receive for the quoted swap.
+
+It should be noted that `quoteExactInputSingle` is only 1 of 4 different methods that the quoter offers:
+
+1. `quoteExactInputSingle` - given the amount you want to swap, produces a quote for the amount out for a swap of a single pool
+2. `quoteExactInput` - given the amount you want to swap, produces a quote for the amount out for a swap over multiple pools
+3. `quoteExactOutputSingle` - given the amount you want to get out, produces a quote for the amount in for a swap over a single pool
+4. `quoteExactOutput`  - given the amount you want to get out, produces a quote for the amount in for a swap over multiple pools
+
+## Next Steps
+
+Now that you're able to make a quote, check out our next guide on [trading](./03-trading.md) using this quote!