Grindery Wallet SDK - v0.5.7

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

GitHub file size in bytes

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.

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, in response to user's action:

// Get your "connect" button element
const button = document.getElementById('your-connect-button-id');

// Add event listener to handle button clicks
button.addEventListener('click', async () => {
  // Call `connect` method in response to user's click
  const [address]: string[] = await WalletSDK.connect();
});

It is important to use connect() method only in response to user's action, to avoid connection approval popup being blocked by the browser.

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.