Skip to content

Latest commit

 

History

History
349 lines (230 loc) · 12.5 KB

README.md

File metadata and controls

349 lines (230 loc) · 12.5 KB
Raw

Grindery Wallet SDK is a JS library that provides a reliable, secure, and seamless connection from your dapp to the Grindery Smart-Wallet.

Grindery Wallet Beta

GitHub package.json dynamic GitHub Actions Workflow Status GitHub Issues or Pull Requests GitHub file size in bytes GitHub Downloads (all assets, all releases) Website GitHub License

The SDK enables your dapp to provide a seamless user experience for Grindery users, without relying on third-party libraries. By integrating your dapp using the SDK, millions of Telegram users can connect the dapp to their Grindery Smart-Wallet.

Table of Contents:

Example implementation

See an example implementation here: https://grindery-io.github.io/grindery-wallet-sdk/example.

Installing SDK

Obtain App ID

To interact with Grindery Wallet your app needs to be registered first.

Go to the Grindery Bot and use /checkout_registerapp command to register an app obtain an App Id.

App Id is required, as it allows Grindery Wallet users to recognize reqests made from your app.

For demo and testing you can use Demo App Id: 763d2695-d237-45fe-bfe8-2e4e26ff707b

Browser

CDN

Place the script tag before the closing </head> tag, using this code:

<script
  data-app-id="your-app-id"
  src="https://grindery-io.github.io/grindery-wallet-sdk/example/dist/grindery-wallet-sdk.umd.production.min.js"
></script>

Download

Download SDK from GitHub: https://github.com/grindery-io/grindery-wallet-sdk

Extract downloaded archive and copy dist/grindery-wallet-sdk.umd.production.min.js file into the root of your project public folder.

Place the script tag before the closing </head> tag, using this code:

<script
  data-app-id="your-app-id"
  src="grindery-wallet-sdk.umd.production.min.js"
></script>

If you are building a Telegram Mini App - make sure to put Grindery script tag AFTER Telegram script.

Node

Wallet SDK is a front-end library. It can be installed via node package managers to use with modern frontend frameworks, but it can't be used on the server side.

At least version 18 Node is required.

Install with NPM:

npm install --save grindery-io/grindery-wallet-sdk

Or Yarn:

yarn add grindery-io/grindery-wallet-sdk

Include module in your code:

import 'grindery-wallet-sdk';

// set app id
window.Grindery.WalletSDK.setAppId('your-app-id');

Alternatively you can set the app id before importing the sdk via window.Grindery object. This can be useful to share the app id between multiple Grindery scripts:

window.Grindery.appId = 'your-app-id';

Then later in your code include the sdk:

import 'grindery-wallet-sdk';

Basic usage

Once the script is loaded, a window.Grindery.WalletSDK object will become available:

const WalletSDK = window.Grindery?.WalletSDK;

Make sure to configre your app id before calling SDK methods. See here how to obtain an app id.

Server connection

The SDK automatically connects to the server when page is loaded. You can check connection status using isConnected() method:

const isConnected: boolean = WalletSDK.isConnected();

You can listen for SDK connect event to catch server connection event:

WalletSDK.on('connect', (chainId: string) => {
  if (WalletSDK.isConnected()) {
    console.log(`Wallet SDK is connected to ${chainId} chain`);
  }
});

Wallet connection

To initiate connection to the Grindery Wallet use connect() method:

WalletSDK.on('connect', async () => {
  const [address]: string[] = await WalletSDK.connect();
});

You can listen for SDK accountsChanged event, to catch when user's wallet is connected:

WalletSDK.on('accountsChanged', (addresses: string[]) => {
  console.log('accountsChanged', addresses);
});

To disconnect user's wallet use disconnect() method (and you can listen for disconnect event):

WalletSDK.on('disconnect',  => {
  console.log('Wallet disconnected');
});

WalletSDK.disconnect();

Silently getting wallet address

The SDK allows dApps to exchange Telegram user ID to user's EVM wallet address.

The method doesn't require user to go through the wallet connection process, and can be executed silently in the background. However, without fully connected wallet a dApp has read-only access, and can't request message signing or transactions sending. To do this ask user to connect the wallet first.

WalletSDK.on('connect', async () => {
  const userId = '123456';
  const telegramUserWallet = await WalletSDK.getUserWalletAddress(userId);
});

This can be especially usefull for Telegram mini-apps, where user ID can be detected automatically. For example:

WalletSDK.on('connect', async () => {
  const telegramUserWallet = await WalletSDK.getUserWalletAddress(
    window.Telegram?.WebApp?.initDataUnsafe?.user?.id
  );
});

Sending transactions

To request transaction sending use sendTransaction() method, once the wallet is connected:

WalletSDK.on('accountsChanged', async (addresses: string[]) => {
  const transactionHash = await WalletSDK.sendTransaction({
    to: '0x0', // required
    value: '', // optional
    data: '', // optional
  });
});

Signing

To sing a custom message using personal signature use signMessage() method, once the wallet is connected:

WalletSDK.on('accountsChanged', async (addresses: string[]) => {
  const signature = await WalletSDK.signMessage('Custom message to sign');
});

Chain switching

To switch the network use switchChain() method, once the wallet is connected:

WalletSDK.on('chainChanged', (chainId: string) => {
  console.log('chainId', chainId);
});
WalletSDK.switchChain('eip155:137');

To get the current network use getChain() method, once the wallet is connected:

WalletSDK.on('accountsChanged', () => {
  console.log('chainId', WalletSDK.getChain());
});

Getting user information

To get information about connected Grindery Wallet User use getUser() method, once the wallet is connected:

WalletSDK.on('accountsChanged', async () => {
  console.log('user', await WalletSDK.getUser());
});

Advanced usage

Full documentation

See full documentation here: https://grindery-io.github.io/grindery-wallet-sdk

Injected Ethereum Provider

Grindery Wallet SDK automatically injects Ethereum Provider API as specified by EIP-1193.

Provider API can be accessed via window.ethereum or window.Grindery.WalletSDK.provider.

Multiple injected providers

If the user has multiple wallet browser extensions installed that inject ethereum providers (e.g., MetaMask or Coinbase Wallet), Grindery Wallet's injected provider will construct a "multiprovider" array at window.ethereum.providers containing the injected provider from each wallet. Grindery Wallet can be identified in this array by the isGrinderyWallet property.

Alternativelly you can detect wallet by listenting to provider announcement events as specified by EIP-6963.

Provider Methods

Method: eth_requestAccounts

Connect a dApp to the Grindery Wallet.

This method must always be called first, to initate dApp connection and get user's wallet address.

Request params: none

Response result: Array of Strings. An array with user addresses.

Method: eth_accounts

Get connected user's wallet addresses.

Request params: none

Response result: Array of Strings. An array of user addresses.

Method: eth_sendTransaction

Request params:

  • to String. Required.
  • value String. Required.
  • data String. Required.

Response result: String. The transaction hash.

Method: personal_sign

Request params:

  • data String. Required.
  • fromAddress String. Required.

Response result: String. The signature.

Method: eth_chainId

Request params: none

Response result: String. Integer ID of the chain as a hexadecimal string, per the eth_chainId Ethereum RPC method.

Method: wallet_switchEthereumChain

Request params:

  • chainId String. Required. Integer ID of the chain as a hexadecimal string, per the eth_chainId Ethereum RPC method.

Response result: null on success.

Changelog

See full changelog here.

SDK Development and building

The SDK library compiled using DTS tool (a fork of TSDX).

See full development documentation here.

License

MIT