Skip to content

Commit

Permalink
docs: docs cleanup part 1
Browse files Browse the repository at this point in the history
  • Loading branch information
@metalboyrick
metalboyrick committed Oct 14, 2024
1 parent aaa113c commit 99bcf2e
Show file tree
Hide file tree
Showing 13 changed files with 81 additions and 516 deletions.
4 changes: 4 additions & 0 deletions docs/hooks/useScaffoldContract.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ sidebar_position: 6

# useScaffoldContract

:::caution
This hook currently only works to read contracts. We apologize for the inconvenience and will work on a fix.
:::

Use this hook to get your contract instance by providing the contract name. It enables you to interact with your contract methods.
For reading data or sending transactions, it's recommended to use `useScaffoldReadContract` and `useScaffoldWriteContract`.

Expand Down
32 changes: 17 additions & 15 deletions docs/hooks/useScaffoldEthBalance.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,26 +34,26 @@ This example demonstrates how to use the `useScaffoldEthBalance` hook to display

## 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.|
| 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. |
| 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. |
| 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).

Expand All @@ -64,15 +64,17 @@ You can also pass other arguments accepted by [useReadContract from starknet-rea
- **`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 });

Expand Down
2 changes: 1 addition & 1 deletion docs/hooks/useScaffoldEventHistory.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ const { data, isLoading, error } = useScaffoldEventHistory({
});
```

This example configures the hook to read events from the YourEvent event of the YourContract smart contract, starting from block 0. It includes block data, but excludes transaction and receipt data. The hook will watch for new events and refresh the data.
This example configures the hook to read events from the `YourEvent` event of the `YourContract` smart contract, starting from block 0. It includes block data, but excludes transaction and receipt data. The hook will watch for new events and refresh the data.

## Configuration

Expand Down
10 changes: 4 additions & 6 deletions docs/hooks/useScaffoldMultiWriteContract.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebar_position: 2

# useScaffoldMultiWriteContract

Use this hook to write to state-changing functions of your smart contract.
Use this hook to batch-write multiple transactions to your smart contract.

```ts
const { sendAsync } = useScaffoldMultiWriteContract({
Expand Down Expand Up @@ -48,7 +48,7 @@ This example demonstrates how to use the `sendAsync`function to send multiple tr

| Parameter | Type | Description |
| :--------------------- | :------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| **calls** | `Array` | Array of configuration objects for the contract calls. Each object should contain `contractName`, `functionName`, and `args`. |
| **calls** | `Calldata[]` | Array of configuration objects for the contract calls. Each object should contain `contractName`, `functionName`, and `args`. |
| **options** (optional) | `InvocationsDetails` | Additional options for the transactions. |

## Call Object Configuration
Expand All @@ -59,10 +59,8 @@ This example demonstrates how to use the `sendAsync`function to send multiple tr
| **functionName** | `string` | Name of the function to call. |
| **args** (optional) | `unknown[]` | Array of arguments to pass to the function (if any). Types are inferred from the contract's function parameters. |

You can also pass other arguments accepted by [writeContractAsync from starknet-react](https://starknet-react.com/hooks/mutation/usecontractwrite).
You can also pass other arguments accepted by [useSendTransaction#sendAsync from starknet-react](https://www.starknet-react.com/docs/hooks/use-send-transaction#sendasync).

## Return Values

- `writeContractAsync` function sends the transaction to the smart contract.
- `isMining` property indicates whether the transaction is currently being mined.
- The extended object includes properties inherited from the useContractWrite hook from starknet-react. You can check the [useContractWrite return values](https://starknet-react.com/hooks/mutation/usecontractwrite) for the types.
- `sendAsync` function sends the transaction(s) to the smart contract.
4 changes: 2 additions & 2 deletions docs/hooks/useScaffoldReadContract.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@ This example retrieves the data returned by the `userGreetingCounter` function o
| **watch** (optional) | `boolean` | Watches and refreshes data on new blocks. (default : `true`) |
| Other arguments | `various` | You can pass other arguments accepted by the useContractRead hook from @starknet-react/core. |

You can also pass other arguments accepted by [useContractRead from Starknet-react](https://starknet-react.com/hooks/query/usecontractread).
You can also pass other arguments accepted by [starknet-react useReadContract](https://www.starknet-react.com/docs/hooks/use-read-contract).

## Return Values

- The retrieved data is stored in the `data` property of the returned object.
- The extended object includes properties inherited from the useContractRead hook of starknet-react. You can check the [useContractRead return values](https://starknet-react.com/hooks/query/usecontractread) documentation for the types.
- The extended object includes properties inherited from the `useReadContract` hook of starknet-react. You can check the [useReadContract return values](https://www.starknet-react.com/docs/hooks/use-read-contract) documentation for the types.
17 changes: 7 additions & 10 deletions docs/hooks/useScaffoldWriteContract.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,13 @@ In this example, the updateGreeting function of the YourContract is called with

## Configuration

| Parameter | Type | Description |
| :-------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------- |
| **contractName** | `string` | Name of the contract to write to. |
| **functionName** | `string` | Name of the function to call. |
| **args** (optional) | `unknown[]` | Array of arguments to pass to the function (if any). Types are inferred from the contract's function parameters. |
| **option** (optional) | `object` | Additional options for the transaction, such as gas and value. |

You can also pass other arguments accepted by [useContractWrite from Starknet-react](https://starknet-react.com/hooks/mutation/usecontractwrite).
| Parameter | Type | Description |
| :------------------ | :---------- | :--------------------------------------------------------------------------------------------------------------- |
| **contractName** | `string` | Name of the contract to write to. |
| **functionName** | `string` | Name of the function to call. |
| **args** (optional) | `unknown[]` | Array of arguments to pass to the function (if any). Types are inferred from the contract's function parameters. |

## Return Values

- The sendAsync method is used to send the write transaction. It returns a promise that resolves when the transaction is confirmed.
- The extended object includes properties inherited from the useContractWrite hook of starknet-react. You can check the [useContractWrite return values](https://starknet-react.com/hooks/mutation/usecontractwrite) documentation for the types.
- The `sendAsync` method is used to send the write transaction. It returns a promise that resolves when the transaction is confirmed.
- The extended object includes properties inherited from the `useSendTransaction` hook of starknet-react. You can check their [documentation](https://www.starknet-react.com/docs/hooks/use-send-transaction#sendasync) for the the sepcific return values.
32 changes: 14 additions & 18 deletions docs/quick-start/accessing-block-explorers.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,26 @@ Starknet block explorers provide users with an interface to access, track, and v

### Features:

| Feature | Description |
|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| **Transaction Tracking** | View and track transactions, including hashes, sender/recipient addresses, and amounts. |
| **Smart Contract Inspection** | Analyze smart contracts, their code, balances, and transaction history. |
| **Block Data Access** | Retrieve block-level information like block numbers, timestamps, and transaction counts. |
| **Address Lookup** | Look up specific addresses to view transaction history, balances, and other on-chain details. |
| Feature | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------- |
| **Transaction Tracking** | View and track transactions, including hashes, sender/recipient addresses, and amounts. |
| **Smart Contract Inspection** | Analyze smart contracts, their code, balances, and transaction history. |
| **Block Data Access** | Retrieve block-level information like block numbers, timestamps, and transaction counts. |
| **Address Lookup** | Look up specific addresses to view transaction history, balances, and other on-chain details. |

## How to Access Starknet Block Explorers:

1. Navigate to the [Scaffold-Stark web app](https://scaffold-stark-demo.vercel.app/) and locate the "Block Explorer" button at the bottom left of the page.

<img src="/img/block-explorer-button.png" alt="block-explorer-button" style={{ width: '50%', height: 'auto' }} />
2. Click the "Block Explorer" button to open a list of available block explorers.
- Navigate your Scaffold Stark project and locate the "Block Explorer" button at the bottom left of the page.

<img src="/img/block-explorer-popup.png" alt="block-explorer-popup" style={{ width: '50%', height: 'auto' }} />
<img src="/img/block-explorer-button.png" alt="block-explorer-button" style={{ width: "50%", height: "auto" }} />

3. Select your preferred block explorer from the list below:
- [Starkscan](https://starkscan.co)
- [Voyager](https://voyager.online)
- [StarkCompass](https://starkcompass.com/)
- Click the "Block Explorer" button to open a list of available block explorers.

4. Based on the chain set in the `Scaffold.config` file, the respective explorers for Sepolia or Mainnet will be provided.
5. You'll be redirected to the chosen block explorer, where you can search for transactions, smart contracts, or addresses using the search bar.
6. Utilize the tabs and filters to further explore and analyze blockchain data.
<img src="/img/block-explorer-popup.png" alt="block-explorer-popup" style={{ width: "50%", height: "auto" }} />

- Based on the chain set in the `Scaffold.config` file, the respective explorers for Sepolia or Mainnet will be provided.
- You'll be redirected to the chosen block explorer, where you can search for transactions, smart contracts, or addresses using the search bar.
- Utilize the tabs and filters to further explore and analyze blockchain data.

For a comprehensive list of all available Starknet explorers, check out [Block explorers](https://docs.starknet.io/documentation/tools/ref_block_explorers/).

Expand Down
Loading

0 comments on commit 99bcf2e

Please sign in to comment.