Merge pull request #1266 from editaahn/editaahn/keplr-679

Add EVM and Starknet support documentation
chainapsis · Jan 3, 2025 · 9a175fa · 9a175fa
2 parents 1d5ec8c + dbd347d
commit 9a175fa
Show file tree

Hide file tree

Showing 4 changed files with 331 additions and 18 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -27,3 +27,7 @@ Keplr is a non-custodial blockchain wallets for webpages that allow users to int
 [Use with secretjs](./api/secretjs.md) describes how to use secretjs with Keplr if you need to use secret-wasm feature.
 
 [Suggest chain](./api/suggest-chain.md) describes how to suggest the chain to Keplr if the chain is not supported natively in Keplr.
+
+[EVM-based chains support](./api/evm.md) describes how to support EVM-based chains with Keplr.
+
+[Starknet Support](./api/starknet.md) describes how to support Starknet chains with Keplr.
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -215,24 +215,6 @@ Using `verifyArbitrary`, you can verify the results requested by `signArbitrary`
 `verifyArbitrary` has been only implemented for simple usage. `verifyArbitrary` returns the result of the verification of the current selected account's sign doc. If the account is not the currently selected account, it would throw an error.  
 
 It is recommended to use `verifyADR36Amino` function in the `@keplr-wallet/cosmos` package or your own implementation instead of using `verifyArbitrary` API.  
-
-### Request Ethereum Signature
-```javascript
-signEthereum(
-  chainId: string,
-  signer: string, // Bech32 address, not hex
-  data: string | Uint8Array,
-  type: 'message' | 'transaction'
-)
-```
-
-This is an experimental implementation of native Ethereum signing in Keplr to be used by dApps on EVM-compatible chains such as Evmos. 
-
-It supports signing either [Personal Messages](https://eips.ethereum.org/EIPS/eip-191) or [Transactions](https://ethereum.org/en/developers/docs/transactions/), with plans to support [Typed Data](https://eips.ethereum.org/EIPS/eip-712) in the future.
-
-Notes on Usage:
-- The `signer` field must be a Bech32 address, not an Ethereum hex address
-- The data should be either stringified JSON (for transactions) or a string message (for messages). Byte arrays are accepted as alternatives for either.
 
 ### Interaction Options
 

diff --git a/docs/api/evm.md b/docs/api/evm.md
@@ -0,0 +1,175 @@
+---
+title: EVM-based Chains Support
+order: 5
+---
+
+# EVM-Based Chain Support
+
+Keplr enables seamless interaction with EVM-based chains, allowing users to utilize its features on Ethereum and other compatible networks. Developers can access the `window.keplr` and `window.keplr.ethereum` objects to leverage various methods for EVM-based interactions.
+
+## Requesting Ethereum Signatures
+
+Keplr supports native Ethereum signing for EVM-based chains, including EVM-compatible Cosmos chains like Evmos. Developers can use the `window.keplr.signEthereum` method to sign:
+
+- [Personal Messages](https://eips.ethereum.org/EIPS/eip-191)  
+- [Transactions](https://ethereum.org/en/developers/docs/transactions/)  
+- [Typed Data](https://eips.ethereum.org/EIPS/eip-712)  
+
+```typescript
+signEthereum(
+  chainId: string,
+  signer: string,
+  data: string | Uint8Array,
+  type: 'message' | 'transaction' | 'eip-712'
+);
+```
+
+**Notes:**
+- The `signer` field supports both Bech32 and Ethereum hex addresses.
+- The `data` parameter can be a stringified JSON (for transactions) or a plain text message (for messages). Byte arrays are also supported.
+
+## Sending Ethereum Transactions
+
+Keplr allows sending Ethereum transactions through the `window.keplr.sendEthereumTx` method. It broadcasts the transaction and returns the transaction hash upon success.
+
+```typescript
+sendEthereumTx(chainId: string, tx: Uint8Array): Promise<string>;
+```
+
+## Suggesting ERC20 Tokens
+
+Users can suggest ERC20 tokens to be added to a chain using the `window.keplr.suggestERC20` method. This process requires user approval.
+
+```typescript
+suggestERC20(chainId: string, contractAddress: string);
+```
+
+## EVM JSON-RPC Requests
+
+Keplr handles EVM JSON-RPC requests via the `window.keplr.ethereum` object, enabling dApps to interact with EVM chains. Supported methods include those for managing accounts, transactions, subscriptions, and chain configurations.
+
+### Supported Request Types
+
+- **`eth_chainId`**: Returns the current chain's EVM chain ID.
+- **`net_version`**: Retrieves the network version.
+- **`eth_accounts` & `eth_requestAccounts`**: Returns the selected address.
+- **`eth_sendTransaction`**: Sends a signed transaction and returns the transaction hash.
+
+  ```typescript
+  params: [
+    {
+      chainId: string | number,
+      from: string,
+      gas?: string,
+      gasLimit?: string,
+    },
+  ];
+  ```
+
+- **`eth_signTransaction`**: Signs a transaction and returns the signed data.
+
+  ```typescript
+  params: [
+    {
+      chainId?: string | number,
+      from: string,
+      gas?: string,
+      gasLimit?: string,
+    },
+  ];
+  ```
+
+- **`personal_sign`**: Signs a personal message.
+
+  ```typescript
+  params: [message: string];
+  ```
+
+- **`eth_signTypedData_v3` & `eth_signTypedData_v4`**: Signs EIP-712 typed data.
+
+  ```typescript
+  params: [signer: string];
+  ```
+
+- **`eth_subscribe` & `eth_unsubscribe`**: Manages subscriptions via WebSocket.
+- **`wallet_switchEthereumChain`**: Switches to a specified chain.
+
+  ```typescript
+  params: [
+    {
+      chainId: string,
+    },
+  ];
+  ```
+
+- **`wallet_addEthereumChain`**: Adds a new EVM chain.
+
+  ```typescript
+  params: [
+    {
+      chainId: string,
+      chainName: string,
+      nativeCurrency: {
+        name: string,
+        symbol: string,
+        decimals: number,
+      },
+      rpcUrls: string[],
+      iconUrls?: string[],
+    },
+  ];
+  ```
+
+- **`wallet_getPermissions`, `wallet_requestPermissions`**: Requests or returns permissions.
+- **`wallet_revokePermissions`**: Revokes permissions.
+  ```typescript
+  params: [
+    {
+      eth_accounts: object
+    },
+  ]
+  ```
+
+- **`wallet_watchAsset`**: Adds an ERC20 asset.
+
+  ```typescript
+  params: {
+    type: string,
+    options: {
+      address: string,
+      symbol?: string,
+      decimals?: number,
+      image?: string,
+      tokenId?: string,
+    },
+  };
+  ```
+
+#### Ethereum-Native Methods
+
+- `eth_call`, `eth_estimateGas`, `eth_getTransactionCount`, `eth_getTransactionByHash`, `eth_getTransactionByBlockHashAndIndex`, `eth_getTransactionByBlockNumberAndIndex`, `eth_getTransactionReceipt`, `eth_sendRawTransaction`, `eth_protocolVersion`, `eth_syncing`, `eth_getCode`, `eth_getLogs`, `eth_getProof`, `eth_getStorageAt`, `eth_getBalance`, `eth_blockNumber`, `eth_getBlockByHash`, `eth_getBlockByNumber`, `eth_gasPrice`, `eth_feeHistory`, `eth_maxPriorityFeePerGas`
+
+Keplr supports Ethereum-native methods following [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) and [EIP-2255](https://eips.ethereum.org/EIPS/eip-2255) standards. For a complete list, refer to the [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/).
+
+## Example Usage
+
+### Requesting Permissions
+
+```typescript
+window.keplr.ethereum.request({
+  method: "wallet_requestPermissions",
+});
+```
+
+### Revoking Permissions
+
+```typescript
+window.keplr.ethereum.request({
+  method: "wallet_revokePermissions",
+  params: [
+    {
+      eth_accounts: "eth_accounts",
+    },
+  ],
+});
+```
diff --git a/docs/api/starknet.md b/docs/api/starknet.md
@@ -0,0 +1,152 @@
+---
+title: Starknet Support
+order: 6
+---
+
+# Starknet Support
+
+## Signing Transactions on Starknet
+
+### Requesting a Starknet Signature
+
+To request a Starknet signature, use the `window.keplr.signStarknetTx` method. This method returns a promise that resolves to an object containing the signed transactions and signer details.
+
+```typescript
+signStarknetTx(
+    chainId: string,
+    transactions: Call[],
+    details: InvocationsSignerDetails
+): Promise<{
+    transactions: Call[];
+    details: InvocationsSignerDetails;
+    signature: string[];
+}>
+```
+
+### Signing a Starknet Deploy Account Transaction
+
+To start interacting with Starknet, users must create an account, which requires a signature. Use the `window.keplr.signStarknetDeployAccountTransaction` method to sign a deploy account transaction.
+
+```typescript
+signStarknetDeployAccountTransaction(
+    chainId: string,
+    transaction: DeployAccountSignerDetails
+): Promise<{
+    transaction: DeployAccountSignerDetails;
+    signature: string[];
+}>
+```
+
+## Retrieving Starknet Keys
+
+You can retrieve Starknet keys and addresses using the following methods:
+
+```typescript
+type Key = {
+  name: string;
+  hexAddress: string;
+  pubKey: Uint8Array;
+  address: Uint8Array;
+  isNanoLedger: boolean;
+};
+
+// Get the Starknet key for a single chain
+getStarknetKey(chainId: string): Promise<Key>;
+
+// Get Starknet keys for multiple chains
+getStarknetKeysSettled(
+  chainIds: string[]
+): Promise<SettledResponses<Key>>;
+```
+
+## Starknet JSON-RPC Requests
+
+The `window.keplr.starknet.request` method enables you to send Starknet JSON-RPC requests. This method supports various request types, which may require specific parameters.
+
+```typescript
+request<T = unknown>({
+  type,
+  params,
+}: {
+  type: string;
+  params?: unknown[] | Record<string, unknown>;
+}): Promise<T>;
+```
+
+### Supported Request Types
+
+- **`wallet_watchAsset`:** Suggest ERC20 tokens.
+  ```typescript
+  params: {
+    type: "ERC20";
+    options: {
+      address: string
+      symbol?: string
+      decimals?: number
+      image?: string
+      name?: string
+    };
+  };
+  ```
+- **`wallet_requestAccounts`:** Retrieve selected Starknet accounts.
+- **`wallet_getPermissions`:** Retrieve Starknet permissions.
+- **`wallet_switchStarknetChain`:** Switch the current chain.
+  ```typescript
+  params: [{ chainId: string }];
+  ```
+- **`wallet_requestChainId`:** Retrieve the current chain ID.
+- **`wallet_addInvokeTransaction`:** Add a Starknet invoke transaction.
+  ```typescript
+  params: {
+    calls: {
+      contract_address: string
+      entry_point: string
+      calldata: RawArgs | Calldata
+    }[]
+  };
+  ```
+- **`wallet_signTypedData`:** Sign Starknet typed data.
+  ```typescript
+  params: { message: StarknetTypedData };
+  ```
+- **`wallet_supportedSpecs`:** Retrieve supported Starknet specifications.
+
+#### Starknet-Native Request Types
+
+- `starknet_addDeclareTransaction`, `starknet_addDeployAccountTransaction`, `starknet_addInvokeTransaction`, `starknet_blockHashAndNumber`, `starknet_blockNumber`, `starknet_call`, `starknet_chainId`, `starknet_estimateFee`, `starknet_getBlockTransactionCount`, `starknet_getBlockWithTxHashes`, `starknet_getBlockWithTxs`, `starknet_getClass`, `starknet_getClassAt`, `starknet_getClassHashAt`, `starknet_getEvents`, `starknet_getNonce`, `starknet_getStateUpdate`, `starknet_getStorageAt`, `starknet_getTransactionByBlockIdAndIndex`, `starknet_getTransactionByHash`, `starknet_getTransactionReceipt`, `starknet_pendingTransactions`, `starknet_simulateTransactions`, `starknet_specVersion`, `starknet_syncing`
+
+For detailed information on Starknet JSON-RPC APIs, refer to the [Starknet API OpenRPC](https://github.com/starkware-libs/starknet-specs/blob/master/api/starknet_api_openrpc.json).
+
+### Examples
+
+#### Suggesting ERC20 Tokens
+
+```typescript
+window.keplr.starknet.request({
+  type: "wallet_watchAsset",
+  params: {
+    type: "ERC20",
+    options: {
+      address: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", // ETH Contract address
+    },
+  },
+});
+```
+
+#### Switching Chains
+
+```typescript
+window.keplr.starknet.request({
+  type: "wallet_switchStarknetChain",
+  params: { chainId: "starknet:SN_SEPOLIA" },
+});
+```
+
+#### Retrieving Transaction Information
+
+```typescript
+window.keplr.starknet.request({
+  type: "starknet_getTransactionByHash",
+  params: { transactionHash: "0x123456789abcdef" },
+});
+```