Grindery Wallet SDK is a JS library that provides a reliable, secure, and seamless connection from your dapp to the Grindery Smart-Wallet.
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.
See an example implementation here: https://grindery-io.github.io/grindery-wallet-sdk/example.
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
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 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.
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';
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.
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`);
}
});
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();
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
);
});
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
});
});
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');
});
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());
});
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());
});
See full documentation here: https://grindery-io.github.io/grindery-wallet-sdk
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
.
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.
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.
eth_accounts
Get connected user's wallet addresses.
Request params: none
Response result: Array of Strings. An array of user addresses.
eth_sendTransaction
Request params:
to
String. Required.value
String. Required.data
String. Required.Response result: String. The transaction hash.
personal_sign
Request params:
data
String. Required.fromAddress
String. Required.Response result: String. The signature.
eth_chainId
Request params: none
Response result: String. Integer ID of the chain as a hexadecimal string, per the eth_chainId
Ethereum RPC 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.
See full changelog here.
The SDK library compiled using DTS tool (a fork of TSDX).
See full development documentation here.
MIT