Merge pull request #28 from Calebux/docs-update

feat: add documentation for useScaffoldStrkBalance and useScaffoldEth…

docs/hooks/useScaffoldEthBalance.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 9
+---
+
+# useScaffoldEthBalance
+
+Use this hook to read the Ethereum (ETH) balance of a specified address on the StarkNet blockchain.
+
+```ts
+const { value, formatted, symbol } = useScaffoldEthBalance({
+  address: "0x01176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8",
+});
+```
+
+This example retrieves the ETH balance for the specified address using the deployed Ethereum contract on StarkNet. The returned object includes the raw balance value, the formatted balance, and the ETH symbol.
+
+## Usage Example
+
+```tsx
+const BalanceDisplay = ({ userAddress }) => {
+  const { formatted, symbol } = useScaffoldEthBalance({ address: userAddress });
+
+  return (
+    <div>
+      <p>
+        Balance: {formatted} {symbol}
+      </p>
+    </div>
+  );
+};
+```
+
+This example demonstrates how to use the `useScaffoldEthBalance` hook to display the formatted ETH balance for a user's address.
+
+## Configuration
+
+| Parameter      | Type                   | Description                                                                                     |
+| :------------- | :--------------------- | :---------------------------------------------------------------------------------------------- |
+| **address**    | `Address \| string`    | The Ethereum address to fetch the balance for. If not provided, the balance of the contract is used.|
+
+## Return Values
+
+| Parameter        | Type          | Description                                                                                                    |
+| :--------------- | :------------ | :------------------------------------------------------------------------------------------------------------- |
+| **value**        | `bigint`      | The raw balance fetched from the contract as a `bigint`.                                                        |
+| **decimals**     | `number`      | Number of decimals for the token. Defaults to `18` for ETH.                                                     |
+| **symbol**       | `string`      | The token symbol. For this contract, it will return `"ETH"`.                                                    |
+| **formatted**    | `string`      | The balance formatted into a human-readable string using ethers' `formatUnits`. Defaults to `"0"` if no balance. |
+
+## Call Object Configuration
+
+| Parameter           | Type        | Description                                                                                                      |
+| :------------------ | :---------- | :--------------------------------------------------------------------------------------------------------------- |
+| **functionName**    | `string`    | Name of the function to call (in this case, `balance_of`).                                                        |
+| **args** (optional) | `unknown[]` | Arguments to pass to the function, such as the target address.                                                    |
+| **blockIdentifier** | `BlockNumber`| Specifies the block to query the contract from, set as `"pending"` by default.                                    |
+
+You can also pass other arguments accepted by [useReadContract from starknet-react](https://starknet-react.com/docs/hooks/queries/usecontractread).
+
+## Return Values
+
+- **`value`**: Raw balance value in `bigint`.
+- **`formatted`**: The balance in human-readable format.
+- **`symbol`**: The token symbol ("ETH").
+- The object also includes properties from the `useReadContract` hook. You can check the [useContractRead return values](https://starknet-react.com/docs/hooks/queries/usecontractread) for additional details.
+
+
+## Best Practices
+- Use this hook in any component where you need to display the ETH balance of a specific address.
+- Ensure that the component using this hook is wrapped in a StarkNet React provider for seamless integration with the blockchain context.
+- For a smooth user experience, handle loading and error states in the component using this hook.
+- Consider using the formatted balance for display purposes as it is easier for users to understand compared to the raw bigint value.
+
+## Error Handling
+The hook does not handle errors explicitly, but the `useReadContract` hook from StarkNet React includes an `error` property in the return object. You can leverage this to manage errors in your component like this:
+```tsx
+const { value, formatted, symbol, error } = useScaffoldEthBalance({ address });
+
+if (error) {
+  return <div>Error fetching ETH balance</div>;
+}
+```

docs/hooks/useScaffoldStrkBalance.md

@@ -0,0 +1,64 @@
+---
+sidebar_position: 8
+---
+
+# useScaffoldStrkBalance
+
+The `useScaffoldStrkBalance` hook is a custom React hook designed to fetch and display the balance of STRK tokens for a given address on the StarkNet blockchain. It simplifies the process of reading contract data by using StarkNet React utilities.
+
+## Usage Example
+
+```ts
+import useScaffoldStrkBalance from './hooks/useScaffoldStrkBalance';
+
+const address = "0x01176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8"
+
+function StrkBalanceDisplay({ address }) {
+  const { value, formatted, symbol } = useScaffoldStrkBalance({ address: "0x01176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8" });
+
+  return (
+    <div>
+      <h3>STRK Balance:</h3>
+      <p>Raw Value: {value}</p>
+      <p>Formatted: {formatted}</p>
+      <p>Symbol: {symbol}</p>
+    </div>
+  );
+}
+```
+
+This example demonstrates how to use the `useScaffoldStrkBalance` hook to display the raw and formatted STRK token balance for a user's address.
+
+## Configuration
+
+| Parameter      | Type                   | Description                                                                                     |
+| :------------- | :--------------------- | :---------------------------------------------------------------------------------------------- |
+| **address**    | `Address \| string`    | The STRK address to fetch the balance for. If not provided, it will attempt to fetch the balance for the current connected account. |
+
+## Return Values
+
+| Parameter        | Type          | Description                                                                                                    |
+| :--------------- | :------------ | :------------------------------------------------------------------------------------------------------------- |
+| **value**        | `bigint`      | The raw STRK balance fetched from the contract as a `bigint`.                                                   |
+| **decimals**     | `number`      | Number of decimals for the token. Defaults to `18` for STRK.                                                    |
+| **symbol**       | `string`      | The token symbol. For this contract, it will return `"STRK"`.                                                   |
+| **formatted**    | `string`      | The balance formatted into a human-readable string using ethers' `formatUnits`.                                 |
+| **error**        | `Error`       | Error object in case there is a failure fetching the balance.                                                   |
+
+## Best Practices
+
+- Use this hook in components that need to display STRK token balances.
+- Ensure that the component using this hook is wrapped in a StarkNet React provider.
+- Handle loading and error states appropriately in the parent component.
+
+## Error Handling
+
+While the hook doesn't explicitly handle errors, the returned props object from `useReadContract` includes an error property that can be checked in the parent component.
+
+```ts
+const { value, formatted, symbol, error } = useScaffoldStrkBalance({ address });
+
+if (error) {
+  return <div>Error fetching STRK balance</div>;
+}
+```