From 455aaec799c1c30393fcd2ef5fe83636c34e2181 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Thu, 19 Sep 2024 21:56:37 +0000 Subject: [PATCH] updates --- .../starknet/architecture.md | 66 +++++++++++++ .../starknet/connect-to-starknet.md | 29 +++--- .../use-non-evm-networks/starknet/index.md | 96 ++++++------------- .../starknet/manage-starknet-accounts.md | 2 +- .../starknet/manage-starknet-networks.md | 1 + .../starknet/sign-starknet-data.md | 3 +- .../use-non-evm-networks/starknet/tutorial.md | 8 +- .../non-evm-apis/starknet-snap-api.md | 13 ++- 8 files changed, 126 insertions(+), 92 deletions(-) create mode 100644 wallet/how-to/use-non-evm-networks/starknet/architecture.md diff --git a/wallet/how-to/use-non-evm-networks/starknet/architecture.md b/wallet/how-to/use-non-evm-networks/starknet/architecture.md new file mode 100644 index 0000000000..8d1d18ecb8 --- /dev/null +++ b/wallet/how-to/use-non-evm-networks/starknet/architecture.md @@ -0,0 +1,66 @@ +--- +description: How does `get-starknet` interact with MetaMask. +sidebar_position: 2 +--- + +# About `get-starknet` + +`get-starknet` is a library that simplifies Starknet network interactions. +It works with the Starknet Snap to extend the functionality of MetaMask and enable dapps to interact with users' Starknet accounts in MetaMask. + +When you integrate `get-starknet` into your dapp, it creates a `WalletAccount` object. `WalletAccount` acts as a connection between dapps and MetaMask and provides a way to manage Starknet interactions. + +This allows users to send Starknet transactions, sign Starknet messages, and manage Starknet accounts within MetaMask, and this functionality can be extended to multiple wallets. + +## How `get-starknet` and MetaMask interact + +A dapp with `get-starknet` installed interacts with MetaMask as follows: + +1. The dapp uses `get-starknet` to request the user connect to MetaMask. If the user doesn't have the Starknet Snap installed, MetaMask automatically prompts the user to connect and approve the addition. + +1. After the dapp is connected to MetaMask and the Starknet Snap, `get-starknet` receives a Starknet Windows Object (SWO), which represents the MetaMask wallet with Starknet functionality. + +1. `get-starknet` creates a [`WalletAccount`](http://starknetjs.com/docs/guides/walletAccount/) instance. This instance manages the Starknet account within MetaMask. + +```mermaid +sequenceDiagram + participant dapp as dapp + participant get as get-starknet + participant mm as MetaMask + participant Snap as Starknet Snap + participant network as Starknet network + + dapp->>get: Initialize connection + get->>mm: Request connection + mm->>Snap: Activate + Snap-->>mm: Activated + mm-->>get: Return SWO + get->>get: Create WalletAccount + get-->>dapp: Connection established + + dapp->>get: Read blockchain data + get->>network: Query data + network-->>get: Return data + get-->>dapp: Processed data + + dapp->>get: Write transaction + get->>mm: Request signature + mm->>Snap: Sign transaction + Snap-->>mm: Signed transaction + mm-->>get: Return signature + get->>network: Submit transaction + network-->>get: Transaction result + get-->>dapp: Transaction confirmation + + mm->>get: Account/Network changed + get->>dapp: Notify change +``` + +The `get-starknet` library offers several key features that improve how dapps interact with the Starknet network through MetaMask: + +- The `WalletAccount` uses a specified provider to access data from the Starknet network. +- For transactions, `get-starknet` prepares the data and sends it to MetaMask for signing through the Starknet Snap. +- `get-starknet` enables the dapp to create contract instances connected to the `WalletAccount`, allowing smart contract functions to be invoked, with MetaMask handling the signatures. +- `get-starknet` sets up listeners for account and network changes in MetaMask, so the dapp can subscribe and update its state accordingly. +- `get-starknet` can request network changes through MetaMask, allowing users to switch between Starknet networks, such as Mainnet or Sepolia testnet. +- `get-starknet` can also request MetaMask to display specific tokens, improving the user experience. \ No newline at end of file diff --git a/wallet/how-to/use-non-evm-networks/starknet/connect-to-starknet.md b/wallet/how-to/use-non-evm-networks/starknet/connect-to-starknet.md index 9ab10feccc..1bfccda5fa 100644 --- a/wallet/how-to/use-non-evm-networks/starknet/connect-to-starknet.md +++ b/wallet/how-to/use-non-evm-networks/starknet/connect-to-starknet.md @@ -8,7 +8,7 @@ import TabItem from "@theme/TabItem"; # Connect your Starknet account to MetaMask -To connect your dapp to the Starknet network in MetaMask, you can use the `get-starknet` library. +To connect your dapp to the Starknet network in MetaMask, you can use the [`get-starknet`](https://github.com/starknet-io/get-starknet) library. This library simplifies the process of connecting to the Starknet Snap, allowing you to interact with users' Starknet accounts in MetaMask. `get-starknet` also enables dapps to interact with other wallets in the Starknet ecosystem. @@ -53,6 +53,7 @@ Add the [`get-starknet`](https://github.com/starknet-io/get-starknet) `version 3 ### 2. Connect to the Snap Create a `src/components` directory, and add a new file named `WalletConnectButton.js` to the directory. Add the following code to the file: + ```javascript title="WalletConnectButton.js" import React, { useState } from "react"; import { connect, disconnect } from "get-starknet"; @@ -77,7 +78,7 @@ function WalletConnectButton() { setWalletName(getWallet?.name || "") } catch(e){ - // handle user rejection to install metamask / snaps here. + // Handle user rejection to install MetaMask / Snaps. console.log(e) } }; @@ -143,7 +144,7 @@ Alternatively, you can manage the Snap invocation manually. Use the `wallet_invo :::note - To connect to Starknet, the dapp user must ensure the [Starknet Snap](https://snaps.metamask.io/snap/npm/consensys/starknet-snap/) is added to MetaMask. +To connect to Starknet, the dapp user must ensure the [Starknet Snap](https://snaps.metamask.io/snap/npm/consensys/starknet-snap/) is added to MetaMask. ::: @@ -190,11 +191,11 @@ Use the `callSnap` function to call a specific Snap method. The following example calls `starkNet_createAccount`: ```javascript -const deploy = false; // Set to true to deploy the actual account -const addressIndex = 0; // Specify which address to derive -const chainId = "0x534e5f5345504f4c4941"; // Specify which chain to use (in this instance the Sepolia testnet) +const deploy = false; // Set to true to deploy the actual account. +const addressIndex = 0; // Specify which address to derive. +const chainId = "0x534e5f5345504f4c4941"; // Chain ID of the network to use. -const accountInfo = await callSnap('starkNet_createAccount', { addressIndex, deploy, chainId }); +const accountInfo = await callSnap("starkNet_createAccount", { addressIndex, deploy, chainId }); ``` #### Example in HTML and Vanilla JS @@ -214,7 +215,7 @@ The following is a full example of a dapp with a button that, when clicked, conn diff --git a/wallet/how-to/use-non-evm-networks/starknet/index.md b/wallet/how-to/use-non-evm-networks/starknet/index.md index 8d9c8487e2..c154747d44 100644 --- a/wallet/how-to/use-non-evm-networks/starknet/index.md +++ b/wallet/how-to/use-non-evm-networks/starknet/index.md @@ -7,91 +7,49 @@ sidebar_position: 1 Starknet is a non-EVM Layer 2 network. To interact with Starknet accounts in MetaMask, you need to use the Starknet Snap. -You can use the `get-starknet` library or the `wallet_invokeSnap` JSON-RPC method to connect to the Starknet Snap. +You can use the [`get-starknet`](https://github.com/starknet-io/get-starknet) library or the `wallet_invokeSnap` JSON-RPC method to connect to the Starknet Snap. - -`get-starknet`: +[`get-starknet`](architecture): - Provides a high-level API that abstracts complex operations. - Offers standardized error handling. - Supports multiple wallets, not limited to MetaMask. - Manages wallet connections and Starknet interactions. - Results are in more readable code. -`wallet_invokeSnap`: +[`wallet_invokeSnap`](../../../../snaps/reference/wallet-api-for-snaps/#wallet_invokesnap): - Requires precise method names and parameter structures. - Handles both MetaMask-specific and Starknet-specific errors. - Is designed for operating within the MetaMask framework. - Manages lower-level Starknet interactions directly. - Provides results in more detailed, lower-level code. - :::note -We recommend using the `get-starknet` library for most use cases. - -::: - -The choice between the two connection methods depends on the specific needs of the project, the desired level of control, and familiarity with Starknet and Snaps. - - -## About `get-starknet` - -`get-starknet` is a library that simplifies Starknet network interactions. -It works with the Starknet Snap to extend the functionality of MetaMask and enable dapps to interact with users' Starknet accounts in MetaMask. +We recommend using the `get-starknet` library for most use cases due to its ease of configuration. -When you integrate `get-starknet` into your dapp, it creates a `WalletAccount` object. `WalletAccount` acts as a connection between dapps and MetaMask and provides a way to manage Starknet interactions. +There are [limitations](#limitations) on the methods that are avilabile when using `get-starknet`. For more information on the methods you can use when interacting with users' Starknet accounts, see the [Starknet Snap API documentation](../../../reference/non-evm-apis/starknet-snap-api.md). -This allows users to send Starknet transactions, sign Starknet messages, and manage Starknet accounts within MetaMask, and this functionality can be extended to multiple wallets. - -### How `get-starknet` and MetaMask interact - -A dapp with `get-starknet` installed interacts with MetaMask as follows: - -1. The dapp uses `get-starknet` to request the user connect to MetaMask. If the user doesn't have the Starknet Snap installed, MetaMask automatically prompts the user to connect and approve the addition. - -1. After the dapp is connected to MetaMask and the Starknet Snap, `get-starknet` receives a Starknet Windows Object (SWO), which represents the MetaMask wallet with Starknet functionality. - -1. `get-starknet` creates a [`WalletAccount`](http://starknetjs.com/docs/guides/walletAccount/) instance. This instance manages the Starknet account within MetaMask. - -```mermaid -sequenceDiagram - participant dapp as dapp - participant get as get-starknet - participant mm as MetaMask - participant Snap as Starknet Snap - participant network as Starknet network - - dapp->>get: Initialize connection - get->>mm: Request connection - mm->>Snap: Activate - Snap-->>mm: Activated - mm-->>get: Return SWO - get->>get: Create WalletAccount - get-->>dapp: Connection established - - dapp->>get: Read blockchain data - get->>network: Query data - network-->>get: Return data - get-->>dapp: Processed data - - dapp->>get: Write transaction - get->>mm: Request signature - mm->>Snap: Sign transaction - Snap-->>mm: Signed transaction - mm-->>get: Return signature - get->>network: Submit transaction - network-->>get: Transaction result - get-->>dapp: Transaction confirmation - - mm->>get: Account/Network changed - get->>dapp: Notify change -``` +::: -The `get-starknet` library offers several key features that improve how dapps interact with the Starknet network through MetaMask: -- The `WalletAccount` uses a specified provider to access data from the Starknet network. -- For transactions, `get-starknet` prepares the data and sends it to MetaMask for signing through the Starknet Snap. -- `get-starknet` enables the dapp to create contract instances connected to the `WalletAccount`, allowing smart contract functions to be invoked, with MetaMask handling the signatures. -- `get-starknet` sets up listeners for account and network changes in MetaMask, so the dapp can subscribe and update its state accordingly. -- `get-starknet` can request network changes through MetaMask, allowing users to switch between Starknet networks, such as Mainnet or Sepolia testnet. -- `get-starknet` can also request MetaMask to display specific tokens, improving the user experience. \ No newline at end of file +## Limitations + +Not all methods are supported by both `get-starknet` and `wallet_invokeSnap`. The following table lists which methods are availabile for the two implemnatations. + +| Method | `wallet_invokeSnap` | `get-starknet` | +|--------|:---:|:---:| +| [`starkNet_createAccount`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_createAccount) | ✓ | | +| [`starkNet_displayPrivateKey`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_displayPrivateKey) | ✓ | | +| [`starkNet_estimateAccountDeployFee`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_estimateAccountDeployFee) | ✓ | | +| [`starkNet_estimateFee`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_estimateFee) | ✓ | | +| [`starkNet_extractPublicKey`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_extractPublicKey) | ✓ | ✓ | +| [`starkNet_getErc20TokenBalance`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_getErc20TokenBalance) | ✓ | | +| [`starkNet_getStoredUserAccounts`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_getStoredUserAccounts) | ✓ | | +| [`starkNet_getTransactions`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_getTransactions) | ✓ | | +| [`starkNet_getTransactionStatus`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_getTransactionStatus) | ✓ | | +| [`starkNet_getValue`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_getValue) | ✓ | | +| [`starkNet_recoverAccounts`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_recoverAccounts) | ✓ | | +| [`starkNet_sendTransaction`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_sendTransaction) | ✓ | | +| [`starkNet_signMessage`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_signMessage) | ✓ | ✓ | +| [`starkNet_upgradeAccContract`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_upgradeAccContract) | ✓ | ✓ | +| [`starkNet_verifyMessage`](../../../reference/non-evm-apis/starknet-snap-api.md#starkNet_verifyMessage) | ✓ | ✓ | diff --git a/wallet/how-to/use-non-evm-networks/starknet/manage-starknet-accounts.md b/wallet/how-to/use-non-evm-networks/starknet/manage-starknet-accounts.md index ee4414619d..4a994c36de 100644 --- a/wallet/how-to/use-non-evm-networks/starknet/manage-starknet-accounts.md +++ b/wallet/how-to/use-non-evm-networks/starknet/manage-starknet-accounts.md @@ -61,7 +61,7 @@ This component displays the connected account address if available, and provides ## Account creation -Account creation in Starknet is handled by the wallet provider. As a dapp developer, you do not create accounts directly. Instead, you guide users to create an account with their preferred wallet provider. +Account creation in Starknet is handled by the wallet provider. As a dapp developer, you do not create accounts directly. Instead, you guide users to [create an account](../connect-to-starknet) with their preferred wallet provider. :::note diff --git a/wallet/how-to/use-non-evm-networks/starknet/manage-starknet-networks.md b/wallet/how-to/use-non-evm-networks/starknet/manage-starknet-networks.md index d4c050ee47..6e4f50d7de 100644 --- a/wallet/how-to/use-non-evm-networks/starknet/manage-starknet-networks.md +++ b/wallet/how-to/use-non-evm-networks/starknet/manage-starknet-networks.md @@ -26,6 +26,7 @@ const checkCurrentNetwork = () => { Starknet currently operates two public networks. Each network is identified by a unique chain ID. Use these chain IDs when configuring your dapp or interacting with the Starknet networks. You can allow users to switch between different Starknet networks by setting the appropriate chain ID. + Starknet has two official networks: | Network | Chain ID (Hexadecimal) | diff --git a/wallet/how-to/use-non-evm-networks/starknet/sign-starknet-data.md b/wallet/how-to/use-non-evm-networks/starknet/sign-starknet-data.md index 619ea2540d..23e2b44aaa 100644 --- a/wallet/how-to/use-non-evm-networks/starknet/sign-starknet-data.md +++ b/wallet/how-to/use-non-evm-networks/starknet/sign-starknet-data.md @@ -5,7 +5,8 @@ sidebar_position: 5 # Sign Starknet transactions -After the account is connected, you can sign a transaction using the `wallet.account.signer.signTransaction` function: +After an account is connected, you can sign a transaction using the `wallet.account.signer.signTransaction` function: + ```typescript const signStarknetTransaction = async (wallet, contractAddress, entrypoint, calldata) => { try { diff --git a/wallet/how-to/use-non-evm-networks/starknet/tutorial.md b/wallet/how-to/use-non-evm-networks/starknet/tutorial.md index dda9cf16e6..adccfbd5bb 100644 --- a/wallet/how-to/use-non-evm-networks/starknet/tutorial.md +++ b/wallet/how-to/use-non-evm-networks/starknet/tutorial.md @@ -1,11 +1,11 @@ --- -description: Starknet integration tutorial +description: Create a basic dapp using `get-starknet` and React TypeScript sidebar_position: 6 --- -# Create a basic dapp with `get-starknet` and React TypeScript +# Create a basic dapp with `get-starknet` -In this tutorial, you'll learn how to set up a basic dapp that uses get-starknet to connect to MetaMask and display the user's wallet address. +In this tutorial, you'll learn how to set up a basic dapp that uses `get-starknet` to connect to MetaMask and display the user's wallet address. ## 1. Project Setup @@ -203,7 +203,7 @@ Now that you have set up the basics, let's go a step further and show how to dis ### 3.1. Setting Up the Contract -To interact with an ERC-20 contract, you'll need to create a Contract instance from starknet.js using the WalletAccount instance. Assuming the ABI is loaded from a JSON file, here's how you would do it: +To interact with an ERC-20 contract, you'll need to create a contract instance from `starknet.js` using the `WalletAccount` instance. Assuming the ABI is loaded from a JSON file, here's how you would do it: ```typescript import { Contract } from "starknet"; diff --git a/wallet/reference/non-evm-apis/starknet-snap-api.md b/wallet/reference/non-evm-apis/starknet-snap-api.md index 1749902a99..1327665dbb 100644 --- a/wallet/reference/non-evm-apis/starknet-snap-api.md +++ b/wallet/reference/non-evm-apis/starknet-snap-api.md @@ -24,13 +24,20 @@ Starknet currently operates two public networks. Each network is identified by a | Network | Chain ID (Hexadecimal) | |---------|------------------------| | Mainnet | `0x534e5f4d41494e` | -| Sepolia testnet | `0x534e5f5345504f4c4941` | +| Testnet (Sepolia) | `0x534e5f5345504f4c4941` | -Use these constants when specifying the network in your Starknet transactions or when configuring your development environment. +Use these IDs when specifying the network in your Starknet transactions or when configuring your development environment. + +Ensure you're using the correct chain ID for your intended network to avoid unintended transactions on the wrong network. :::note -Always verify you're using the correct chain ID for your intended network to avoid unintended transactions on the wrong network. +Currently, `get-starknet` only works with the following methods: + +- [`starkNet_extractPublicKey`](#starknet_extractpublickey) +- [`starkNet_signMessage`](#starknet_signmessage) +- [`starkNet_upgradeAccContract`](#starknet_upgradeacccontract) +- [`starkNet_verifyMessage`](#starknet_verifymessage) :::