Simple Summary
An RPC method for switching the wallet’s active Starknet Chain.
Inspired by EIP-3326.
Abstract
The wallet_switchStarknetChain RPC method allows Starknet decentralized applications (“dapps”) to request that the wallet switches its active Starknet chain. The caller must specify a chain ID, and the method returns null if the active chain was switched, and an error otherwise.
Important cautions for implementers of this method are included in the Security Considerations section.
Motivation
With the deprecation of goerli2, all dapps on Starknet are built on either mainnet or testnet - goerli, with some dapps implementing both e.g block explorers.
Most wallets only supports interacting with one chain at a time. We call this the wallet’s “active chain”. Since Starknet users are expected to interact with either of both chains, [mainnet or goerli], it’s important to enable dapps to be able to switch the user’s chain to the appropriate one.
wallet_switchStarknetChain enables dapps to request that the wallet switches its active chain to whichever one is required by the dapp. This improves the UX for both dapps and wallets by a long mile.
Specification
Method - wallet_switchStarknetChain
The method accepts a single object parameter with a chainId field. The method returns null if the wallet switched its active chain, and an error otherwise.
NB: The method presupposes that the wallet has a concept of a single “active chain”. The active chain is defined as the chain that the wallet is forwarding RPC requests to.
export interface SwitchStarknetChainParameter {
chainId: string // A 0x-prefixed hexadecimal string
}
Parameters
The method as specified above, accepts a single parameter chainId.
The chainId:
- MUST be the integer ID of the chain, specified as a 0x-prefixed hexadecimal string.
The wallet:
- MUST recognize the specified ID, able to switch to the specified chain and capable of servicing RPC requests to it.
Returns
The method MUST return null if the request was successful, and an error otherwise.
Example
These examples use JSON-RPC, but the method could be implemented using other RPC protocols.
To switch to Mainnet:
{
"id": 1,
"jsonrpc": "2.0",
"method": "wallet_switchStarknetChain",
"params": [
{
"chainId": "0x534e5f4d41494e",
}
]
}
To switch to the Goerli testnet:
{
"id": 1,
"jsonrpc": "2.0",
"method": "wallet_switchStarknetChain",
"params": [
{
"chainId": "0x534e5f474f45524c49",
}
]
}
Code example with get-starknet:
Request
await window.starknet.request({
type: "wallet_switchStarknetChain",
params: {
chainId: "SN_MAIN"
}
});
Result
"null"
Practical example as implemented by Element
A dapp that currently implements this standard, is Element. When a user connects his wallet, but on the wrong chain, he gets prompted to connect to the right chain.
The request to switch network, looks like this on the Argent X wallet, but could be improved:
Security Consideration
For wallets with a concept of an active chain, switching the active chain has significant implications for pending RPC requests and the user’s experience. If the active chain switches without the user’s awareness, a malicious dapp could induce the user to take actions for unintended chains.
In light of this, the wallet:
- SHOULD display a confirmation whenever a
wallet_switchStarknetChainrequest is received, clearly identifying the requester and the chain that will be switched to. - SHOULD cancel all pending RPC requests and chain-specific user confirmations when switching.