Add Recipes section

[Pabl0cks]

Working on this PR to add Recipes section to Docs. It's my first time documenting this kind of code examples, so perhaps my approach is totally wrong, would love candid feedback if so 😊

Tried to give all recipes the same structure:

• Title
• Short description
• Before You Begin. In this section I'm trying to give a bit of technical context with links to the docs of all the hooks/components/utils used in the example.
• Implementation (steps)
• Conclusion
• Full Recipe Code

Recipes created:

• Get the Current Balance of the Connected Account
• Write to a Contract with writeAsync button
• Wait for Transaction Receipt to Send a Second Transaction
• Contract Interaction with useTransactor and useContractWrite
• Read a uint from a contract and display it in a nice way (maybe with & without params)
• Imperatively writing to a contract (passing args to writeAsync). Not sure if this would be redundant after explaining it a bit in "Write to contract with writeAsync button"

Would love a initial technical overview to check if the code examples, explanations, doc naming and titles make sense.

Any feedback that you have would be appreciated ♥🙌

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
scaffold-eth-2-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 21, 2023 8:48am

[carletex]

Thanks for working on this @Pabl0cks! We definitely need to think about a structure and then apply it to all recipes.

The one you are proposing seems a bit verbose to me. A simpler idea:

• h1 title
• brief description (no need to have a h2) just the text
• Full Recipe code (no need to have a h2) just the code.
• Some code explanation. I see 2 options here: add some comments in the code VS a more detailed explanation like you did (steps)

I don't think we need: "before you begin", "Step 4: Add the component to your Application", "Step 5: Test and Deploy" and "Conclusion"

---

Maybe you could take one of the recipes, duplicate it, and make it this way. We can keep iterating until we find one that we all like.

[Pabl0cks]

Thanks for the feedback @carletex ♥ Agree that a simplified structure/content will be more useful for users.

I've just pushed SimplifiedGetCurrentBalanceFromAccount.md with the simplified approach.

I've added a couple comments with some sentences I was not sure if keep them or delete them.

Let me know how do see this new approach, if you want I can create a 2nd version of it with the implementation guide as VS comments 🙌

[technophile-04]

Tysm @Pabl0cks for tackling and setting this up 🙌

Along the lines of Carlos comment #33 (comment)

1. What if we use Line highlighting, so that we can focus on main thing and it allows us from skipping some extra explanation steps.

2. (Not sure about this point) but what if move Full code block to last section which contains nicely styled components and in Implentation guide we just explain with unstyled html so that we focus on main things more but also provide copy-pastable styled components if anyone wants to use

Will also try to explore other options, But I think we are almost there 🙌

Here is the code snipped for above image:

---
sidebar_position: 1
title: Simplified Get balance of the connected account
description: Learn how to retrieve and display the ETH balance of the connected account in your dApp.
---

# Get the Current Balance of the Connected Account

This recipe shows how to fetch and display the ETH balance of the currently connected account in your decentralized application.

## Implementation guide

### Step 1: Create a new Component

Begin by creating a new component in the `components` folder of your application.

\`\`\`tsx title="components/ConnectedAddressBalance.tsx"
export const ConnectedAddressBalance = () => {
  return (
    <div>
      <h2>Your Ethereum Balance</h2>
    </div>
  );
};
\`\`\`

### Step 2: Retrieve the Connected Account

Fetch the Ethereum address of the currently connected account using the [useAccount wagmi hook](https://wagmi.sh/react/hooks/useAccount) and easily display them using Scaffold ETH-2 [Address](/components/Address) and [Balance](/components/Balance) components

\`\`\`tsx title="components/ConnectedAddressBalance.tsx"
// highlight-start
import { useAccount } from "wagmi";
import { Address, Balance } from "~~/components/scaffold-eth";
// highlight-end

export const ConnectedAddressBalance = () => {
  // highlight-start
  const { address: connectedAddress } = useAccount();
  // highlight-end

  return (
    <div>
      // highlight-start
      <h2>Your Ethereum Balance</h2>
      Address: <Address address={connectedAddress} />
      Balance: <Balance address={connectedAddress} />
      // highlight-end
    </div>
  );
};
\`\`\`

## Full Recipe Code

\<details>\
  \<summary>\Here's the complete code for the "ConnectedAddressBalance" component along with styles:\</summary>\

\`\`\`tsx
import type { NextPage } from "next";
import { useAccount } from "wagmi";
import { Address, Balance } from "~~/components/scaffold-eth";

const YourBalance: NextPage = () => {
  const { address: connectedAddress } = useAccount();

  return (
    <div className="bg-base-300 p-6 rounded-lg max-w-md mx-auto mt-6">
      <h2 className="text-lg font-bold mb-2">Your Ethereum Balance</h2>

      <div className="text-sm font-semibold mb-2">
        Address: <Address address={connectedAddress} />
      </div>

      <div className="text-sm font-semibold">
        Balance: <Balance address={connectedAddress} />
      </div>
    </div>
  );
};

export default YourBalance;
\`\`\`

\</details\>


\`\`\`


</details>

[Pabl0cks]

What if we use Line highlighting, so that we can focus on main thing and it allows us from skipping some extra explanation steps.

(Not sure about this point) but what if move Full code block to last section which contains nicely styled components and in Implentation guide we just explain with unstyled html so that we focus on main things more but also provide copy-pastable styled components if anyone wants to use

TYSM for the feedback @technophile-04!! Always so valuable ♥

I've just pushed some changes:

• Fixed bugs and tried to simplify explanations on SimplifiedGetCurrentBalanceFromAccount.tsx
• Used GetCurrentBalanceFromAccount.tsx to include Shiv's approach in order to compare easier between both.

My personal view on both versions:

• I like the SimplifiedGet... approach of having the code on top for the advanced devs, and the guide below for the people that are still learning. Feels optimized for both profiles.
• From Get... approach I love the highlights and having the component name on top, but in the case of this example, which might be too easy, feels a bit overkill, we are highlighting almost everything 🙃 For bigger recipes, where we may be working with more than 1 file, or with more lines of code, I think it may make more sense and will let the user have an easier time following the recipe.
• Get... content with the iterative approach also makes sense to me, where you keep improving your component until you get the final usable code. The only con may be having the full recipe code at the end.

For not experienced devs I really dont know which approach may be more useful, probably is a bit subjective on how each one tends to solve problems. Experienced devs may just want the recipe code and ignore the rest 😂

[carletex]

What do you all think ?

🚀 🚀 I think is great!

[edakturk14]

First of all - this is GREAT!!

I agree with @technophile-04, only thing is that I think it's good to have the code snippet collapsable.

I like the way it is here: (We can change the H# and have it after the description)

Small difference :) If you all think that having the code block open is better we can do that to. What do you think?

[Pabl0cks]

What do you all think ?

I LOVE it, think it's the way to go. Both the experienced and the new developers will have a great experience with that approach.

Will try to implement a first version of this approach for all of the current Recipes 🙌

[Pabl0cks]

I've just pushed some changes to try to implement the new approach for WriteToContractWriteAsyncButton and WaitTxApprovalReceiptLaunchNextTx to the iterative approach 🙌.

Feel like the WaitTxApprovalReceiptLaunchNextTx could be better sliced/explained, but prefer to wait for your review, just in case you don't like that example/recipe. Also was not sure if should add a link to NftMarketplace.sol source code and deploy script in case someone wanted to try the recipe itself.

It has also some styles that could be deleted to simplify the example, or we could add more styling to other recipes if you see it better this way.

I agree with @technophile-04, only thing is that I think it's good to have the code snippet collapsable.

For now I left them all expanded, since I think they like to save the extra click for the advanced devs, but in some cases where the Recipe's code is too long, I agree it can feel a bit overwhelming to new developers.

[technophile-04]

but in some cases where the Recipe's code is too long, I agree it can feel a bit overwhelming to new developers.

What if we use collapsible and keep it opened by default? (not sure if docusaurus has this option)

Feel like the WaitTxApprovalReceiptLaunchNextTx could be better sliced/explained, but prefer to wait for your review, just in case you don't like that example/recipe. Also was not sure if should add a link to NftMarketplace.sol source code and deploy script in case someone wanted to try the recipe itself.

Just an idea :

what if provide with a externalContract code deployed at sepolia and tell people to copy-paste it in their externalContract.ts file at the start of the recipe and switch targetNetwork to sepolia before following with recipe? and it will be collapsed by default

Another option might be give them the solidity code and deploy manually but I think this will make recipe a bit long

But yeah I think we need to find a way to provide people abi / solidity code because if we don't then the recipe code will give type errors if they copy paste it directly.

---

Regarding WaitTxApprovalReceiptLaunchNextTx example if I look closely I feel that's more of we are teaching people how to use wagmi's useContractWrite hook and wait for its trasactionReceipt using publicClient because if you use SE-2 useScaffoldContractWrite hook by default we are already waiting for txnReceipt there.

But yeah I completely get why we added this recipe 🙌, In case we are planning to keep it maybe we deploy a very simple SpenderContract on sepolia to demonstrate this whole workflow instead of using NFTMarketplace contract.

Here is an bad example contract to demonstrate:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
contract TokenBurner {
    function burnTokens(address tokenAddress, uint256 amount) external onlyOwner {
        IERC20 token = IERC20(tokenAddress);
        // Transfer tokens to the zero address (burn)
        token.transferFrom(msg.sender, address(0),amount);
    }
}

We first approve some amount on DAI contract for TokenBurner to spend and then we call burnTokens on TokenBurner contract.

But yeah let's see what others have to say.

Tysm @Pabl0cks, other examples are already looking great I feel 🙌 !!

[Pabl0cks]

What if we use collapsible and keep it opened by default? (not sure if docusaurus has this option)

I like the idea! We can always choose to leave it closed by default in some recipe edge-cases with too much code. Haven't seen a native way to do it, but can be easily done adding a style in the custom.css. Just pushed it, so we can check how we like it 🙌

[Pabl0cks]

what if provide with a externalContract code deployed at sepolia and tell people to copy-paste it in their externalContract.ts file at the start of the recipe and switch targetNetwork to sepolia before following with recipe? and it will be collapsed by default

I like this idea 🙌 We could add for example an ::info or ::tip below the full code snippet, explaining the use of externalContract to interact with external contracts and providing the code for it to work.

Regarding WaitTxApprovalReceiptLaunchNextTx example if I look closely I feel that's more of we are teaching people how to use wagmi's useContractWrite hook and wait for its trasactionReceipt using publicClient because if you use SE-2 useScaffoldContractWrite hook by default we are already waiting for txnReceipt there.

I think you're right and then there is probably no sense for the WaitTxApprovalReceiptLaunchNextTx recipe.

Maybe it would make sense to create an ERC20ApprovePattern recipe using an already deployed sepolia ERC20 token for the example? Or not for now.

[technophile-04]

Just pushed it, so we can check how we like it 🙌

LGTM !!

Maybe it would make sense to create an ERC20ApprovePattern recipe using an already deployed sepolia ERC20 token for the example?

Yup yup, I already added a basic minimal example TokenBurner contract at #33 (comment) which can help us demonstrate this flow 🙌, but maybe let's wait to see @carletex and @edakturk14 are sold on idea of deploying examples sepolia contracts.........And for ERC20ApprovePattern if TokenBurner makes sense or if there is a more sensible / better way to demo this flow

Thanks Pablo 🙌

[edakturk14]

Thank you so much @Pabl0cks - The recipes addition is looking very good!! And thanks a lot @technophile-04 for the comments on the TokenBurner contract example. Tbh i didn't exactly know that part, so learning on the way. So I don't have a strong example or preference. I can say that I do like the example of ERC20ApprovePattern, its simple and demonstrates the point.

[technophile-04]

Tysm @Pabl0cks !! and others for great suggestions 🙌 ! Looking really nice !!

Discussed with Carlos and removed wait for transaction receipt and send next transaction for now since it required a different contract and created #47 for discussion.

Merging this, I think we have left this todo from #25 :

• Read a uint from a contract and display it in a nice way (maybe with & without params)

Let's tackle it another PR since this already got too long and looks great for the initial iteration 🙌

[carletex]

Great work all <3

[edakturk14]

This is great, thank you so much!!! 🤩🤩🤩