Simple Summary
A JavaScript Starknet Provider API for consistency across clients and applications.
Inspired by EIP-1193.
Abstract
A common convention in the Starknet web application (“dapp”) ecosystem is for key management software (“wallets”) to expose their API via a JavaScript object in the web page. This object is called “the Provider”.
This SIMP formalizes a Starknet Provider API to promote wallet interoperability. The API is designed to be minimal, event-driven, and agnostic of transport and RPC protocols. Its functionality is easily extended by defining new RPC methods and message event types.
Specification
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”,
and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.
Definitions
This section is non-normative.
- Provider
A JavaScript object made available to a consumer, that provides access to Ethereum by means of a Client. - Client
An endpoint that receives Remote Procedure Call (RPC) requests from the Provider, and returns their results. - Wallet
An end-user application that manages private keys, performs signing operations, and acts as a middleware between the Provider and the Client. - Remote Procedure Call (RPC)
A Remote Procedure Call (RPC), is any request submitted to a Provider for some procedure that is to be processed by a Provider, its Wallet, or its Client.
Connectivity
The Provider is said to be “connected” when it can service RPC requests to at least one chain.
The Provider is said to be “disconnected” when it cannot service RPC requests to any chain at all.
To service an RPC request, the Provider must successfully submit the request to the remote location, and receive a response. In other words, if the Provider is unable to communicate with its Client, for example due to network issues, the Provider is disconnected.
API
Interface written in typescript is available in Appendix I
Properties
id
Type: string
A unique identifier for the wallet provider.
Used by dapps to easily identify a wallet.
- The id MUST be unique among all wallet providers.
- The id SHOULD NOT change between different versions of the wallet provider.
name
Type: string
The name of the wallet.
Can be used by dapps to display the list of available wallets during connection process.
version
Type: string
TRhe version of the wallet implementation.
Dapps could use it to adapt to changes between two versions of a wallet provider.
- The version SHOULD use semver
icon
Type: string
An image as a base64 encoded string representing the icon/logo of the wallet provider.
Can be used by dapps to display the list of available wallets during connection process.
- The icon MAY be implemented
- The icon format MUST be an image encoded in base64
Methods
request
Based on EIP-2696
Type: <T extends RpcMessage>(call: Omit<T, "result">) => Promise<T["result"]>
Usage example with specific RPC method:
interface RpcMessage {
type: string;
params?: any;
result: never;
}
interface extends RpcMessageSwitchChain {
type: "wallet_switchStarknetChain"
params: SwitchStarknetChainParameter
result: boolean
}
const switchChainSuccess = await Provider.request<RpcMessageSwitchChain>(args: RequestArguments);
addListener
Based on NodeJS EventEmitter
Type: addListener(eventName: string, listener: (...params: unknown[]) => void): void
This methods enable dapps to register to a specific event.
removeListener
Based on NodeJS EventEmitter
Type: removeListener(eventName: string, listener: (...params: unknown[]) => void): void
This methods enable dapps to register to a specific event.
Events
connect
Based on EIP-1193
interface ProviderConnectInfo {
readonly chainId: string;
}
Provider.on('connect', listener: (connectInfo: ProviderConnectInfo) => void): Provider;
disconnect
Based on EIP-1193
interface ProviderRpcError extends Error {
message: string;
code: number;
data?: unknown;
}
Provider.on('disconnect', listener: (error: ProviderRpcError) => void): Provider;
chainChanged
Based on EIP-1193
The Provider emits chainChanged when connecting to a new chain.
Provider.on('chainChanged', listener: (chainId: string) => void): Provider;
The event emits a hexadecimal string chainId.
accountsChanged
Based on EIP-1193
The Provider emits accountsChanged if the accounts returned from the Provider (eth_accounts) change.
Provider.on('accountsChanged', listener: (accounts: AccountInterface[]) => void): Provider;
message??
Based on EIP-1193
interface ProviderMessage {
readonly type: string;
readonly data: unknown;
}
Provider.on('message', listener: (message: ProviderMessage) => void): Provider;
Appendix
Appendix I
ProviderInterface comes from starknetjs
interface RequestArguments {
readonly type: string;
readonly params?: readonly unknown[] | object;
}
interface WalletProviderInterface {
id: string;
name: string;
version: string;
icon?: string;
provider: ProviderInterface;
request(args: RequestArguments): Promise<unknown>;
addListener(event: string, listener: (...args: unknown[]) => void): this;
removeListener(event: string, listener: (...args: unknown[]) => void): this;
}