docs: add docs for Earn component, hooks, and utilities
#1981
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| import { | ||
| DepositAmountInput, | ||
| DepositBalance, | ||
| DepositButton, | ||
| Earn, | ||
| EarnDeposit as EarnDepositComponent, | ||
| EarnDetails, | ||
| useEarnContext, | ||
| } from '@coinbase/onchainkit/earn'; | ||
| import App from './App.tsx'; | ||
|
|
||
| const VAULT_ADDRESS = '0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A'; | ||
|
|
||
| export function EarnMain() { | ||
| return ( | ||
| <App> | ||
| <Earn vaultAddress={VAULT_ADDRESS} /> | ||
| </App> | ||
| ); | ||
| } | ||
|
|
||
| export function EarnDeposit() { | ||
| return ( | ||
| <App> | ||
| <Earn vaultAddress={VAULT_ADDRESS}> | ||
| <div className="flex justify-center bg-[var(--ock-bg-primary)] py-2 text-[var(--ock-text-inverse)]"> | ||
| Custom header | ||
| </div> | ||
| <EarnDepositComponent /> | ||
| <div className="flex justify-center bg-[var(--ock-bg-primary)] py-2 text-[var(--ock-text-inverse)]"> | ||
| Custom footer | ||
| </div> | ||
| </Earn> | ||
| </App> | ||
| ); | ||
| } | ||
|
|
||
| export function RearrangedEarnDeposit() { | ||
| return ( | ||
| <App> | ||
| <Earn vaultAddress={VAULT_ADDRESS}> | ||
| <EarnDepositComponent> | ||
| <EarnDetails /> | ||
| <DepositBalance /> | ||
| <DepositAmountInput className="border-2 border-green-400" /> | ||
| <DepositButton /> | ||
| </EarnDepositComponent> | ||
| </Earn> | ||
| </App> | ||
| ); | ||
| } | ||
|
|
||
| const predefinedAmounts = ['0.1', '1', '10']; | ||
|
|
||
| function CustomDepositInterface() { | ||
| const { depositAmount, setDepositAmount } = useEarnContext(); | ||
|
|
||
| return ( | ||
| <EarnDepositComponent> | ||
| <EarnDetails /> | ||
| <div className="grid grid-cols-3 gap-2"> | ||
| {predefinedAmounts.map((amount) => { | ||
| const selected = amount === depositAmount; | ||
| return ( | ||
| <button | ||
| key={amount} | ||
| type="button" | ||
| onClick={() => setDepositAmount(amount)} | ||
| className={`rounded-md px-4 py-2 ${selected ? 'bg-[var(--ock-bg-primary)] text-[var(--ock-text-inverse)]' : 'bg-[var(--ock-bg-secondary)] text-[var(--ock-text-primary)]'}`} | ||
| > | ||
| {amount} | ||
| </button> | ||
| ); | ||
| })} | ||
| </div> | ||
| <DepositButton /> | ||
| </EarnDepositComponent> | ||
| ); | ||
| } | ||
|
|
||
| export function PredefinedInputDeposit() { | ||
| return ( | ||
| <App> | ||
| <Earn vaultAddress={VAULT_ADDRESS}> | ||
| <CustomDepositInterface /> | ||
| </Earn> | ||
| </App> | ||
| ); | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # `buildDepositToMorphoTx` | ||
|
|
||
| The `buildDepositToMorphoTx` function is used to build [Calls](/transaction/types#calls) for depositing an asset to Morpho. These calls can be passed the `<Transaction />` component to send a transaction. | ||
|
|
||
| ## Usage | ||
|
|
||
| ```tsx twoslash [code] | ||
| import { buildDepositToMorphoTx } from '@coinbase/onchainkit/earn'; | ||
|
|
||
| const calls = await buildDepositToMorphoTx({ | ||
| vaultAddress: '0x...', // Morpho vault address on Base | ||
| tokenAddress: '0x...', // Address of the token to deposit | ||
| amount: 1000000000000000000n, // Amount of tokens to deposit | ||
| recipientAddress: '0x...', // Address of the recipient | ||
| }); | ||
| ``` | ||
|
|
||
| ## Returns | ||
|
|
||
| [`Call[]`](/transaction/types#calls) | ||
|
|
||
| ## Parameters | ||
|
|
||
| [`DepositToMorphoParams`](/earn/types#deposittomorphoparams) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # `buildWithdrawFromMorphoTx` | ||
|
|
||
| The `buildWithdrawFromMorphoTx` function is used to build [Calls](/transaction/types#calls) for withdrawing an asset from Morpho. These calls can be passed the `<Transaction />` component to send a transaction. | ||
|
|
||
| ## Usage | ||
|
|
||
| ```tsx twoslash [code] | ||
| import { buildWithdrawFromMorphoTx } from '@coinbase/onchainkit/earn'; | ||
|
|
||
| const calls = await buildWithdrawFromMorphoTx({ | ||
| vaultAddress: '0x...', // Morpho vault address on Base | ||
| amount: 1000000000000000000n, // Amount of tokens to withdraw | ||
| recipientAddress: '0x...', // Address of the recipient | ||
| }); | ||
| ``` | ||
|
|
||
|
|
||
| ## Returns | ||
|
|
||
| [`Call[]`](/transaction/types#calls) | ||
|
|
||
| ## Parameters | ||
|
|
||
| [`WithdrawFromMorphoParams`](/earn/types#withdrawfrommorphoparams) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,206 @@ | ||
| --- | ||
| title: <Earn /> · OnchainKit | ||
| description: Earn interest on your crypto with OnchainKit | ||
| --- | ||
|
|
||
| import { EarnMain, EarnDeposit, RearrangedEarnDeposit, PredefinedInputDeposit } from '../../components/EarnComponents'; | ||
|
|
||
| # `<Earn />` | ||
|
|
||
| The `Earn` component provides a simple interface for earning interest on your crypto via Morpho vaults on Base. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| Before using the `Earn` component, ensure you've completed the [Getting Started](/getting-started) steps. | ||
|
|
||
| ### Starting a new project | ||
|
|
||
| If you're starting a new project, we recommend using `create onchain` to scaffold your project. | ||
|
|
||
| ```bash | ||
| npm create onchain@latest | ||
| ``` | ||
|
|
||
| ### Adding to an existing project | ||
|
|
||
| If you're adding `Earn` to an existing project, simply install OnchainKit. | ||
|
|
||
| :::code-group | ||
|
|
||
| ```bash [npm] | ||
| npm install @coinbase/onchainkit | ||
| ``` | ||
|
|
||
| ```bash [yarn] | ||
| yarn add @coinbase/onchainkit | ||
| ``` | ||
|
|
||
| ```bash [pnpm] | ||
| pnpm add @coinbase/onchainkit | ||
| ``` | ||
|
|
||
| ```bash [bun] | ||
| bun add @coinbase/onchainkit | ||
| ``` | ||
|
|
||
| ::: | ||
|
|
||
| Wrap the `<OnchainKitProvider />` around your app, following the steps in [Getting Started](/getting-started#add-providers). | ||
|
|
||
| ## Quickstart | ||
|
|
||
| To use `Earn`, you'll need to provide a `vaultAddress` prop. A vault address can be obtained from Morpho's [Vaults page](https://app.morpho.org/base/earn). | ||
|
|
||
| ```tsx twoslash | ||
| // @noErrors: 2307 | ||
| import { Earn } from '@coinbase/onchainkit/earn'; // [!code focus] | ||
|
|
||
| <Earn vaultAddress="0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A" /> // [!code focus] | ||
| ``` | ||
|
|
||
| <EarnMain /> | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Custom components and layouts | ||
|
|
||
| `Earn` accepts a `children` prop that can be used to render `Earn` subcomponents or custom components. | ||
|
|
||
| For instance, you can render the `EarnDeposit` component by itself within the `Earn` component, along with any other custom components you'd like to render. | ||
|
|
||
| ```tsx twoslash | ||
| // @noErrors: 2307 | ||
| import { Earn, EarnDeposit } from '@coinbase/onchainkit/earn'; | ||
|
|
||
| <Earn vaultAddress="0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A"> | ||
| <div>Custom header</div> | ||
| <EarnDeposit /> | ||
| <div>Custom footer</div> | ||
| </Earn> | ||
| ``` | ||
|
|
||
| <EarnDeposit /> | ||
|
|
||
| For more granular control, you can also render lower level subcomponents within `EarnDeposit` and `EarnWithdraw`. These subcomponents accept `className` props to customize their styles. | ||
|
|
||
| ```tsx twoslash | ||
| // @noErrors: 2307 | ||
| import { Earn, EarnDeposit, EarnDetails, DepositBalance, DepositAmountInput, DepositButton } from '@coinbase/onchainkit/earn'; | ||
|
There was a problem hiding this comment. nit: these imports cut off, import in multiple lines |
||
|
|
||
| <Earn vaultAddress="0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A"> | ||
| <EarnDeposit> | ||
| <EarnDetails /> | ||
| <DepositBalance /> | ||
| <DepositAmountInput className="border-2 border-green-400" /> | ||
| <DepositButton /> | ||
| </EarnDeposit> | ||
| </Earn> | ||
| ``` | ||
|
|
||
| <RearrangedEarnDeposit /> | ||
|
|
||
| ### Customizing styles | ||
|
|
||
| The `Earn` component is best styled via a [OnchainKit theme](/guides/themes#custom-theme). You can also override individual component styles using `className`. | ||
|
|
||
|
|
||
| ## Advanced Usage | ||
| If you'd like to implement your own custom components, you can use `useEarnContext` within an `Earn` component to access context and build your own components. | ||
|
|
||
| You can find the full interface for `EarnContextType` on the [Types page](/earn/types#earncontexttype). | ||
|
|
||
| Below, we use `useEarnContext` to implement a custom deposit interface by using `useEarnContext` to access the `depositAmount` and `setDepositAmount` context values. | ||
|
|
||
| :::code-group | ||
|
|
||
| ```tsx twoslash [index.tsx] | ||
| // @noErrors: 2307 | ||
| import { Earn, useEarnContext } from '@coinbase/onchainkit/earn'; | ||
| import { CustomDepositButtons } from './custom-deposit-buttons'; | ||
|
|
||
| <Earn vaultAddress="0x7BfA7C4f149E7415b73bdeDfe609237e29CBF34A"> | ||
| <CustomDepositButtons /> | ||
| </Earn> | ||
|
|
||
| ``` | ||
|
|
||
| ```tsx twoslash [custom-deposit-buttons.tsx] | ||
| import {EarnDetails, EarnDeposit, useEarnContext, DepositButton} from '@coinbase/onchainkit/earn'; | ||
| const predefinedAmounts = ['0.1', '1', '10']; | ||
|
|
||
| function CustomDepositButtons() { | ||
| const { depositAmount, setDepositAmount } = useEarnContext(); | ||
|
|
||
| return ( | ||
| <EarnDeposit> | ||
| <EarnDetails /> | ||
| <div className="grid grid-cols-3 gap-2"> | ||
| {predefinedAmounts.map((amount) => { | ||
| const selected = amount === depositAmount; | ||
| return ( | ||
| <button | ||
| key={amount} | ||
| type="button" | ||
| onClick={() => setDepositAmount(amount)} | ||
| className={`rounded-md px-4 py-2 ${selected ? 'bg-[var(--ock-bg-primary)] text-[var(--ock-text-inverse)]' : 'bg-[var(--ock-bg-secondary)] text-[var(--ock-text-primary)]'}`} | ||
|
|
||
| > | ||
| {amount} | ||
| </button> | ||
| ); | ||
| })} | ||
| </div> | ||
| <DepositButton /> | ||
| </EarnDeposit> | ||
| ); | ||
| } | ||
| ``` | ||
| ::: | ||
|
|
||
| <PredefinedInputDeposit /> | ||
|
|
||
| Taking advantage of the data and methods provided by `useEarnContext`, developers can implement fully custom deposit and withdraw interfaces, modifying everything from UI elements to input behavior. | ||
|
|
||
|
|
||
| ## Components | ||
|
|
||
| The `Earn` component includes the following subcomponents: | ||
|
|
||
| - `<Earn />` - A fully built Withdraw and Deposit component. Also includes a `children` prop to render custom components and provides `useEarnContext` to access the context values. | ||
| - `<EarnProvider />` - A headless provider that provides the `useEarnContext` hook to the `Earn` component. | ||
| - `<EarnDeposit />` - A fully built deposit card. | ||
| - `<EarnWithdraw />` - A fully built withdraw card. | ||
| - `<EarnDetails />` - A component that displays the details of the vault. | ||
| - `<DepositAmountInput />` - A component that handles the deposit amount input. | ||
| - `<DepositBalance />` - A component that displays the balance underlying asset in the user's wallet. | ||
| - `<DepositButton />` - A component that triggers the deposit transaction. | ||
| - `<WithdrawAmountInput />` - A component that handles the withdraw amount input. | ||
| - `<WithdrawBalance />` - A component that displays how much the user can withdraw from a vault. | ||
| - `<WithdrawButton />` - A component that triggers the withdraw transaction. | ||
| - `<YieldDetails />` - A component that displays the yield details of the vault. | ||
| - `<VaultDetails />` - A component that displays the vault details. | ||
|
|
||
|
|
||
| ## Hooks | ||
|
|
||
| - [`useEarnContext`](/hooks/use-earn-context) - A hook that provides the context values of the `Earn` component. | ||
| - [`useBuildDepositToMorphoTx`](/hooks/use-build-deposit-to-morpho-tx) - A hook that builds a deposit transaction to Morpho. | ||
| - [`useBuildWithdrawFromMorphoTx`](/hooks/use-build-withdraw-from-morpho-tx) - A hook that builds a withdraw transaction from Morpho. | ||
| - [`useMorphoVault`](/hooks/use-morpho-vault) - A hook that provides the details of a Morpho vault. | ||
|
|
||
| ## Props | ||
|
|
||
| - [`LifecycleStatus`](/earn/types#lifecyclestatus) | ||
| - [`EarnReact`](/earn/types#earnreact) | ||
| - [`EarnProviderReact`](/earn/types#earnproviderreact) | ||
| - [`EarnContextType`](/earn/types#earncontexttype) | ||
| - [`EarnAmountInputReact`](/earn/types#earnamountinputreact) | ||
| - [`DepositAmountInputReact`](/earn/types#depositamountinputreact) | ||
| - [`WithdrawAmountInputReact`](/earn/types#withdrawamountinputreact) | ||
| - [`EarnBalanceReact`](/earn/types#earnbalancereact) | ||
| - [`DepositBalanceReact`](/earn/types#depositbalancereact) | ||
| - [`WithdrawBalanceReact`](/earn/types#withdrawbalancereact) | ||
| - [`EarnDepositReact`](/earn/types#earndepositreact) | ||
| - [`EarnWithdrawReact`](/earn/types#earnwithdrawreact) | ||
| - [`EarnDetailsReact`](/earn/types#earndetailsreact) | ||
| - [`DepositButtonReact`](/earn/types#depositbuttonreact) | ||
| - [`WithdrawButtonReact`](/earn/types#withdrawbuttonreact) | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this page being displayed?