diff --git a/apps/base-docs/docs/connecting-to-the-blockchain/overview-of-providers.md b/apps/base-docs/docs/connecting-to-the-blockchain/blockchain-providers.md similarity index 63% rename from apps/base-docs/docs/connecting-to-the-blockchain/overview-of-providers.md rename to apps/base-docs/docs/connecting-to-the-blockchain/blockchain-providers.md index 49dfc6571c..7df6c0b042 100644 --- a/apps/base-docs/docs/connecting-to-the-blockchain/overview-of-providers.md +++ b/apps/base-docs/docs/connecting-to-the-blockchain/blockchain-providers.md @@ -1,5 +1,5 @@ --- -title: Overview of Providers +title: Blockchain Providers description: Learn what providers are and why you need one. hide_table_of_contents: false --- @@ -8,19 +8,9 @@ Onchain apps need frontends, sometimes called dApps, to enable your users to int --- -## Prerequisites - -Before this lesson, you should: - -- Be familiar with modern, frontend web development -- Possess a general understanding of the EVM and smart contracts -- Ideally, understand how to build a frontend with [Next.js] - ---- - ## Objectives -By the end of this lesson you should be able to: +By the end of this guide you should be able to: - Compare and contrast public providers vs. vendor providers vs. wallet providers - Select the appropriate provider for several use cases @@ -29,9 +19,9 @@ By the end of this lesson you should be able to: ## Types of Providers -In blockchain development, the term _provider_ describes a company or service that provides an API enabling access to the blockchain as a service. This is distinct from the provider in the the React Context API or Redux Provider, though you will also wrap your app with `wagmiConfig` in a similar manner. +In blockchain development, the term _provider_ describes a company or service that provides an API enabling access to the blockchain as a service. This is distinct from the providers you wrap your app in using the [React Context API], though you'll use one of those to pass your blockchain provider deeply into your app. -These services enable interacting with smart contracts without the developer needing to run and maintain their own blockchain node. Running a node is expensive, complicated, and challenging. In most cases, you'll want to start out with a provider. Once you start to get traction, you can evaluate the need to run your own node, or switch to a more advanced architecture solution, such as utilizing [Subgraph]. +These services enable interacting with smart contracts without the developer needing to run and maintain their own blockchain node. Running a node is expensive, complicated, and challenging. In most cases, you'll want to start out with a provider. Once you start to get traction, you can evaluate the need to [run your own node], or switch to a more advanced architecture solution, such as utilizing [Subgraph]. Figuring out which type of provider to use can be a little confusing at first. As with everything blockchain, the landscape changes rapidly and search results often return out-of-date information. @@ -47,7 +37,7 @@ You'll encounter providers divided into three general categories: Public Provide ### Public Providers -Many tutorials and guides, as well getting started guides for libraries such as [wagmi], will use a _Public Provider_ as the default to get you up and running. Public means that they're open, permissionless, and free, so the guides will also usually warn you that you need to add another provider if you don't want to run into rate limiting. Listen to these warnings! The rate-limits of public providers are severe and you'll start getting limited very quickly. +Many tutorials and guides, including the getting started guide for [wagmi], use a _Public Provider_ as the default to get you up and running. Public means that they're open, permissionless, and free, so the guides will also usually warn you that you need to add another provider if you don't want to run into rate limiting. Listen to these warnings! The rate-limits of public providers are severe and you'll start getting limited very quickly. In wagmi, the `publicClient` is just a wrapper setting up a [JSON RPC] provider using the `chain` and `rpcUrls` listed in Viem's directory of chain information. For example, you can view the [data for Base Goerli here]. @@ -55,7 +45,7 @@ Most chains will list this information in their docs as well. For example, on th ### Wallet Providers -Many wallets, including Coinbase and Metamask, inject an Ethereum provider into the browser, as defined in [EIP-1193]. The injected provider is accessible via `window.ethereum`. +Many wallets, including Coinbase Wallet and Metamask, inject an Ethereum provider into the browser, as defined in [EIP-1193]. The injected provider is accessible via `window.ethereum`. Under the hood, these are also just JSON RPC providers. Similar to public providers, they are rate-limited. @@ -63,22 +53,22 @@ Older tutorials for early libraries tended to suggest using this method for gett ### Vendor Providers -A growing number of vendors provide access to blockchain nodes as a service. Visiting the landing pages for [Quicknode] (formerly Quiknode), [Blockdaemon], or [Alchemy] can be a little confusing. Each of these vendors provides a wide variety of services, SDKs, and information. +A growing number of vendors provide access to blockchain nodes as a service. Visiting the landing pages for [Quicknode] or [Alchemy] can be a little confusing. Each of these vendors provides a wide variety of services, SDKs, and information. -Luckily, you can skip most of this if you're just trying to get your frontend connected to you smart contracts, because most of it is handled by wagmi/Viem. You'll just need to sign up for an account and get an endpoint, or a key, and configure your app to connect to the provider(s) you choose. +Luckily, you can skip most of this if you're just trying to get your frontend connected to your smart contracts. You'll just need to sign up for an account and get an endpoint, or a key, and configure your app to connect to the provider(s) you choose. It is worth digging in to get a better understanding of how these providers charge you for their services. The table below summarizes some of the more important API methods, and how you are charged for them by each of the above providers. Note that the information below may change, and varies by network. Each provider also has different incentives, discounts, and fees for each level of product. They also have different allowances for calls per second, protocols, and number of endpoints. Please check the source to confirm! -| | [Alchemy Costs] | [Blockdaemon Costs] | [Quicknode Costs] | -| --------------- | ---------------- | ------------------- | ----------------- | -| Free Tier / Mo. | 3M compute units | 3M compute units | 50M credits | -| Mid Tier / Mo. | 1.5B CUs @ $199 | 30M CUs @ $199 | 3B credits @ $299 | -| eth_blocknumber | 10 | 1 | 20 | -| eth_call | 26 | 10 | 20 | -| eth_getlogs | 75 | 50 | 20 | -| eth_getbalance | 19 | 5 | 20 | +| | [Alchemy Costs] | [Quicknode Costs] | +| :-------------- | :--------------- | :---------------- | +| Free Tier / Mo. | 3M compute units | 50M credits | +| Mid Tier / Mo. | 1.5B CUs @ $199 | 3B credits @ $299 | +| eth_blocknumber | 10 | 20 | +| eth_call | 26 | 20 | +| eth_getlogs | 75 | 20 | +| eth_getbalance | 19 | 20 | To give you an idea of usage amounts, a single wagmi `useContractRead` hook set to `watch` for changes on a single `view` will call `eth_blocknumber` and `eth_call` one time each, every 4 seconds. @@ -90,7 +80,6 @@ In this article, you've learned how Providers supply blockchain connection as a --- -[Next.js]: https://nextjs.org/ [Subgraph]: https://thegraph.com/docs/en/developing/creating-a-subgraph/ [wagmi]: https://wagmi.sh/react/getting-started#configure-chains [data for Base Goerli here]: https://github.com/wagmi-dev/viem/blob/main/src/chains/definitions/baseGoerli.ts @@ -98,8 +87,9 @@ In this article, you've learned how Providers supply blockchain connection as a [Optimism]: https://community.optimism.io/docs/useful-tools/networks/ [EIP-1193]: https://eips.ethereum.org/EIPS/eip-1193 [Alchemy]: https://www.alchemy.com/ -[Blockdaemon]: https://www.blockdaemon.com/ [Quicknode]: https://www.quicknode.com/ [Alchemy Costs]: https://docs.alchemy.com/reference/compute-unit-costs -[Blockdaemon Costs]: https://docs.blockdaemon.com/reference/ethereum-compute-units [Quicknode Costs]: https://www.quicknode.com/api-credits/base +[smart contract development]: https://base.org/camp +[run your own node]: https://docs.base.org/guides/run-a-base-node +[React Context API]: https://react.dev/learn/passing-data-deeply-with-context diff --git a/apps/base-docs/docs/connecting-to-the-blockchain/configuring-providers-sbs.md b/apps/base-docs/docs/connecting-to-the-blockchain/connecting-with-a-provider.md similarity index 85% rename from apps/base-docs/docs/connecting-to-the-blockchain/configuring-providers-sbs.md rename to apps/base-docs/docs/connecting-to-the-blockchain/connecting-with-a-provider.md index d5053bcc03..ec4bb0c31d 100644 --- a/apps/base-docs/docs/connecting-to-the-blockchain/configuring-providers-sbs.md +++ b/apps/base-docs/docs/connecting-to-the-blockchain/connecting-with-a-provider.md @@ -1,5 +1,5 @@ --- -title: Overview of Providers +title: Connecting with a Provider description: Configure several providers and use them to connect to the blockchain. hide_table_of_contents: false --- @@ -8,19 +8,9 @@ hide_table_of_contents: false --- -## Prerequisites - -Before this lesson, you should: - -- Be familiar with modern, frontend web development -- Possess a general understanding of the EVM and smart contracts -- Ideally, understand how to build a frontend with [Next.js] - ---- - ## Objectives -By the end of this lesson you should be able to: +By the end of this guide you should be able to: - Set up a provider in wagmi and use it to connect a wallet - Protect API keys that will be exposed to the front end @@ -130,7 +120,7 @@ Let's add [QuickNode] to the list. It isn't [included in the library] by default import { jsonRpcProvider } from 'wagmi/providers/jsonRpc'; ``` -Unlike the linked example indicates, you do **not** need to add an import `chain` from `'wagmi'` (Their example appears out of date at the time of writing). +Unlike the linked example indicates, you do **not** need to add an import `chain` from `'wagmi'`, unless you're setting up a more complex provider configuration and want to dynamically build RPC urls for multiple chains. You do need an RPC URL, so open up [QuickNode]'s site and sign up for an account if you need to. The free tier will be adequate for now, you may need to scroll down to see it. Once you're in, click `Endpoints` on the left side, then click `+ Create Endpoint`. @@ -169,37 +159,6 @@ Now, the app will use your Quicknode endpoint for the Base network, and fall bac To test this out, comment out `publicProvider()`, and switch networks a few times. Unfortunately, wagmi won't generate an error when you try to connect to a network unsupported by the provider, but you will notice that the wallet balance is only shown correctly for Base, and no longer updates when you switch to other networks. -### Blockdaemon - -You'll also need an account with [Blockdaemon], if you want to use it as a JSON RPC provider. Log in, [or create an account], navigate to the `API Suite` tab on the left, and click `Create API Key`. - -![Create api key](../../assets/images/connecting-to-the-blockchain/blockdaemon-create-key.png) - -You can find the [urls for different networks] in their docs. To connect to Base, add the below to your list of providers: - -```typescript -const { chains, publicClient, webSocketPublicClient } = configureChains( - [mainnet, optimism, base], - [ - // other providers - jsonRpcProvider({ - rpc: () => ({ - http: 'https://svc.blockdaemon.com/base/mainnet/native/http-rpc?apiKey=', - }), - }), - publicProvider(), - ], -); -``` - -:::caution - -This key is also exposed publicly! Be sure to configure an allowlist before deploying! - -::: - -TODO PENDING MORE INFORMATION!!! - ### Alchemy [Alchemy] is [baked into wagmi], but you still need an account and a key. Create an account and/or sign in, navigate to the `Apps` section in the left sidebar, and click `Create new app`. @@ -224,7 +183,7 @@ import { alchemyProvider } from 'wagmi/providers/alchemy'; const { chains, publicClient, webSocketPublicClient } = configureChains( [mainnet, optimism, base], [ - // jsonRPC Providers + // other providers alchemyProvider({ apiKey: 'yourAlchemyApiKey' }), publicProvider(), ], @@ -241,7 +200,6 @@ In this guide, you've learned how to connect your app to the blockchain using se --- -[Next.js]: https://nextjs.org [wagmi]: https://wagmi.sh [Rainbowkit]: https://www.rainbowkit.com [quick start]: https://www.rainbowkit.com/docs/installation @@ -251,10 +209,7 @@ In this guide, you've learned how to connect your app to the blockchain using se [included in the library]: https://github.com/wagmi-dev/wagmi/tree/main/packages/core/src/providers [JSON RPC provider]: https://wagmi.sh/react/providers/jsonRpc [Alchemy]: https://www.alchemy.com/ -[Blockdaemon]: https://www.blockdaemon.com/ [QuickNode]: https://www.quicknode.com/ [allowlist]: https://docs.alchemy.com/docs/how-to-add-allowlists-to-your-apps-for-enhanced-security [baked into wagmi]: https://wagmi.sh/react/providers/alchemy -[create an account]: https://app.blockdaemon.com/signin/register - -[urls for different networks] +[smart contract development]: https://base.org/camp diff --git a/apps/base-docs/docs/connecting-to-the-blockchain/overview.md b/apps/base-docs/docs/connecting-to-the-blockchain/overview.md new file mode 100644 index 0000000000..918e9253a0 --- /dev/null +++ b/apps/base-docs/docs/connecting-to-the-blockchain/overview.md @@ -0,0 +1,43 @@ +--- +title: Overview +description: What's in this learning material. +hide_table_of_contents: false +--- + +# Overview of Connecting to the Blockchain + +These guides show you how to connect your frontend to the blockchain using JSON RPC blockchain providers, and the [Rainbowkit], [Wagmi], and [Viem] stack. + +--- + +## Objectives + +By the end of these guides, you should be able to: + +### Blockchain Providers + +- Compare and contrast public providers vs. vendor providers vs. wallet providers +- Select the appropriate provider for several use cases + +### Connecting with a Provider + +- Set up a provider in wagmi and use it to connect a wallet +- Protect API keys that will be exposed to the front end + +--- + +## Prerequisites + +### 1. Be familiar with modern, frontend web development + +In this guide, we'll be working with a React frontend build with [Next.js]. While you don't need to be an expert, we'll assume that you're comfortable with the basics. + +### 2. Possess a general understanding of the EVM and smart contract development + +These guides assume that you're reasonably comfortable writing basic smart contracts. If you're just getting started, jump over to our [Basecamp] guides and start learning! + +[Basecamp]: https://base.org/camp +[Next.js]: https://nextjs.org/ +[Rainbowkit]: rainbowkit.com/ +[Wagmi]: https://wagmi.sh/ +[Viem]: https://viem.sh/ diff --git a/apps/base-docs/sidebars.js b/apps/base-docs/sidebars.js index 381460f04a..3d60c8c0c2 100644 --- a/apps/base-docs/sidebars.js +++ b/apps/base-docs/sidebars.js @@ -127,6 +127,28 @@ module.exports = { }, ], }, + { + type: 'category', + label: 'Connecting to the Blockchain', + collapsible: true, + items: [ + { + type: 'doc', + id: 'connecting-to-the-blockchain/overview', + className: 'sidebar-reading', + }, + { + type: 'doc', + id: 'connecting-to-the-blockchain/blockchain-providers', + className: 'sidebar-reading', + }, + { + type: 'doc', + id: 'connecting-to-the-blockchain/connecting-with-a-provider', + className: 'sidebar-coding', + }, + ], + }, ], }, ],