From ace74d268c4ed38db59a98912f749fe02e9c7557 Mon Sep 17 00:00:00 2001 From: Julia Ortiz Date: Wed, 21 Feb 2024 15:30:39 -0300 Subject: [PATCH] improves docs --- README.md | 86 ------------------ packages/dappstore-sdk/README.md | 135 ++++++++++++++++++++++++++++ packages/dappstore-sdk/src/index.ts | 1 - 3 files changed, 135 insertions(+), 87 deletions(-) delete mode 100644 README.md create mode 100644 packages/dappstore-sdk/README.md diff --git a/README.md b/README.md deleted file mode 100644 index b109073..0000000 --- a/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# DAppStore SDK client - -## Standalone usage: - -```ts -import { createDAppStoreClient } from "@evmos/dappstore-sdk"; - -// Waits for the client to establish a connection to the DAppStore -await dappstore.initialized; - -console.log( - `DAppStore client initialized.`, - `Chain ID: ${dappstore.chainId}, Accounts: ${dappstore.accounts}` -); // -> DAppStore client initialized. Chain ID: evmos:1, Accounts: ["0x..."] -``` - -## Subscribe to account and chain id changes: - -```ts -// Shorthand for dappstore.provider.on("accountsChanged", (accounts) => { ... }) -dappstore.onAccountsChange((accounts) => { - console.log(`Accounts changed: ${accounts}`); // -> Accounts changed: ["0x..."] -}); - -// Shorthand for dappstore.provider.on("chainChanged", (chainId) => { ... }) -dappstore.onChainChange((chainId) => { - console.log(`Chain changed: ${chainId}`); // -> Chain changed: evmos:1 -}); - -// Or interact directly with the provider -dappstore.provider - .request({ method: "eth_requestAccounts" }) - .then((accounts) => { - console.log(`Accounts: ${accounts}`); // -> Accounts: ["0x..."] - }); -``` - -## Usage with React: - -```tsx -const dappstore = createDAppStoreClient(); -import { useEffect, useState } from "react"; - -const useAccounts = () => { - const [accounts, setAccounts] = useState<`0x${string}`[]>(dappstore.accounts); - useEffect(() => { - return dappstore.onAccountsChange(setAccounts); // <- returns cleanup function - }, []); - return accounts; -}; - -const useChainId = () => { - const [chainId, setChainId] = useState(dappstore.chainId); - useEffect(() => { - return dappstore.onChainChange(setChainId); - }, []); - return chainId; -}; - -const App = () => { - const accounts = useAccounts(); - return
Accounts: {accounts.join(", ")}
; -}; -``` - -## Send a transaction: - -```ts -const sendTransaction = async (to: `0x${string}`) => { - const [from] = dappstore.accounts; - if (!from) { - throw new Error("No account connected"); - } - - return await dappstore.provider.request({ - method: "eth_sendTransaction", - params: [ - { - from, - to, - value: "0x1", // We recommend using a library like ethers.js or viem to handle amounts - }, - ], - }); -}; -``` diff --git a/packages/dappstore-sdk/README.md b/packages/dappstore-sdk/README.md new file mode 100644 index 0000000..dd6d380 --- /dev/null +++ b/packages/dappstore-sdk/README.md @@ -0,0 +1,135 @@ +# DAppStore SDK Client + +The DAppStore SDK Client is a toolkit to help you develop Instant DApps Widgets directly for Evmos DAppstore. + +## What are Instant DApps? + +Instant DApps are DApps featured in Evmos DAppstore that can be interacted with directly from the DAppstore. Essentially, they are widgets embeded in an iframe that gives users the ability to seamlessly interact with a DApp created by other developers. + +## Why use the DAppStore SDK Client? + +The DAppStore SDK Client main function is to provide a simple way to interact with the Evmos DAppstore from inside your DApp. Iframes allows us to securely embed third party content into our page, but it also comes with some limitations. Iframes are sandboxed and do not have access to the parent window, which means it will not have access to the user's wallet connections, forcing the them to connect their wallet again, and the developer to implement a wallet connection flow. + +That not only adds complexity, but also creates an inconsistent user experience. The DAppStore SDK Client solves this problem by providing a way to interact with the Evmos DAppstore directly from the iframe, by implementing an EIP-1193 compliant provider that communicates with the DAppStore wallet connection. + +Because it's an EIP-1193 provider, it can be used with any library that supports it, like ethers.js, web3.js, viem, etc. + +## Getting started + +The quickest way to get started is to use the `dappstore` CLI to create a new project: + +1. First, create a new project with the framework of your choice, Ex. `create-react-app`: + +```sh +npx create-react-app my-instant-dapp +cd ./my-instant-dapp +``` + +2. Then, use the `dappstore` CLI to setup the DAppStore SDK Client: + +```sh +# npm +npx dappstore init +# yarn +yarn dappstore init +# pnpm +pnpm dlx dappstore init +# bun +bunx dappstore init +``` + +3. This will install the necessary dependencies, create a `src/dappstore.ts` file that initializes the DAppStore SDK Client and provider, and add a script to your `package.json` to start the development server with the DAppStore SDK Client. After that you can start your project, and the DAppStore dev environment. + +```sh +# Starts next +npm run dev +# Starts DAppStore dev environment +npm run dev:dappstore +``` + +4. Navigate to http://localhost:1337 to see your DApp running in the DAppStore dev environment. + +## Manual setup + +If you prefer to set up the DAppStore SDK Client manually, you can do so by following these steps: + +1. Install the DAppStore SDK Client and the DAppStore CLI: + +```sh +npm install @evmos/dappstore-sdk dappstore +``` + +2. Start the DAppStore dev environment: + +```sh +npx dappstore dev --target 3000 # <- or the port your app is running on +``` + +3. Initialize the DAppStore SDK Client in your app: + +```ts +import { createDAppStoreClient } from "@evmos/dappstore-sdk"; + +export const dappstore = createDAppStoreClient(); + +/** + * EIP-1193 provider + */ +export const provider = dappstore.provider; +``` + +### Standalone usage: + +```ts +import { createDAppStoreClient } from "@evmos/dappstore-sdk"; + +export const dappstore = createDAppStoreClient(); + +dappstore.provider + .request({ method: "eth_requestAccounts" }) + .then((accounts) => { + console.log(`Accounts: ${accounts}`); // -> Accounts: ["0x..."] + }); +``` + +### Send a transaction: + +```ts +const sendTransaction = async (to: `0x${string}`) => { + const [from] = dappstore.accounts; + if (!from) { + throw new Error("No account connected"); + } + + return await dappstore.provider.request({ + method: "eth_sendTransaction", + params: [ + { + from, + to, + value: "0x1", // We recommend using a library like ethers.js or viem to handle amounts + }, + ], + }); +}; +``` + +### With ethers.js: + +```ts +import { ethers } from "ethers"; +import { createDAppStoreClient } from "@evmos/dappstore-sdk"; + +export const dappstore = createDAppStoreClient(); + +const provider = new ethers.BrowserProvider(dappstore.ethereum); + +const signer = await provider.getSigner(); + +const sendTransaction = async (to: `0x${string}`) => { + return await signer.sendTransaction({ + to, + value: ethers.utils.parseEther("0.1"), + }); +}; +``` diff --git a/packages/dappstore-sdk/src/index.ts b/packages/dappstore-sdk/src/index.ts index 422799b..1dfd946 100644 --- a/packages/dappstore-sdk/src/index.ts +++ b/packages/dappstore-sdk/src/index.ts @@ -1,2 +1 @@ export { createDAppStoreClient, type DAppStoreClient } from "./client"; -export * from "./types/EIP1193Provider";