SDK
Overview
The Dialect SDK is a single typescript library for interacting with Dialect's on and off chain resources. These resources include:
Messaging
All messaging, user to user or dapp to user, is powered by the same Dialect messaging protocol, which supports both on and off chain messaging. With the messaging SDK you can:
- view all message threads
- create & delete threads, &
- send & receive messages within threads.
Dapp Notifications & Subscriptions
In addition to general messaging, Dialect supports an API for dapps to send notifications to their users, both via the Dialect messaging protocols, as well as via web2 channels, including email, Telegram, & SMS.
To support this, the Dialect SDK includes APIs for:
- dapps to register themselves using their messaging keypair.
- wallets to opt in to receiving messages from dapps.
- wallets to configure what channels they'd like to receive dapp messages to, including wallet (using Dialect's protocol), email, Telegram, & SMS.
Authentication
- For all on-chain transactions, authentication & authorization is baked in since wallets must sign all transactions.
- For all off-chain requests, the Dialect API requires all requests to be authenticated using the wallet
signMessagemethod, which proves that the entity making the request has custody of the wallet keypair in question.
Messaging
Create an SDK client & connect your wallet to it
Run the create-solana-sdk example script.
To use the Dialect SDK, you'll need to create an SDK client with an assigned wallet to:
import {
Backend,
ConfigProps,
Dialect,
DialectSolanaWalletAdapterWrapper,
EncryptionKeysStore,
NodeDialectSolanaWalletAdapter,
TokenStore,
} from '@dialectlabs/sdk';
import type {
DialectSdk,
} from '@dialectlabs/sdk';
// Backends tell the SDK where messages can be sent and received to, & in what priority.
const backends = [Backend.DialectCloud, Backend.Solana];
// Provide configuration options for how to target the DialectCloud backend
const dialectCloud = {
url: 'https://dialectapi.to',
// Provide a keystore for storing authentication headers, which are expiring tokens generated from the wallet's signMessage method
tokenStore: TokenStore.createInMemory(),
};
// Convenience for setting smart defaults for backends. Variables above are optional if this is provided.
const environment = 'production';
// Provide a keystore for storing e.g. encryption & decryption keys.
const encryptionKeysStore = EncryptionKeysStore.createInMemory();
// Provide override parameters for Solana backend configuration, including RPC url
const solana = {
rpcUrl: 'https://api.mainnet-beta.solana.com',
};
// A node wallet for running in a node environment. N.b. this would be a mobile or web wallet object instead. The Wrapper class handles conversion to the API expected by the Dialect SDK, but is mostly consistent with expected wallet APIs.
const wallet = DialectSolanaWalletAdapterWrapper.create(
// IMPORTANT: must set environment variable DIALECT_SDK_CREDENTIALS
// to your dapp's Solana messaging wallet keypair e.g. [170,23, . . . ,300]
NodeDialectSolanaWalletAdapter.create(),
);
// Now construct the SDK client from all of the above
const sdk: DialectSdk = Dialect.sdk({
backends,
dialectCloud,
environment,
encryptionKeysStore,
solana,
wallet,
} as ConfigProps);
Get existing threads for a wallet
Run the get-threads example script.
import type {
// ... previous imports
Thread,
ThreadId,
} from '@dialectlabs/sdk';
// ... code from previous examples
// Fetch all threads the wallet is a part of, across all provided backends
const threads: Thread[] = await sdk.threads.findAll();
Note that the threads returned here are fetched from both on- and off-chain backends: Backends.Solana & Backends.DialectCloud.
Get a thread by its id & read thread messages
Run the get-messages example script.
import type {
// ... previous imports
Message,
} from '@dialectlabs/sdk';
// ... code from previous examples
// Choose a given thread
const thread = threads[0];
// Fetch for a single thread by its id. N.b. the ThreadId type specifies both the address of the thread *as well as* the specified backend; threads of a given id may exist in any kind of backend. See the ThreadId type.
const query: FindThreadByIdQuery = {
id: thread.id,
}
const thread = await sdk.threads.find(query);
// Call the messages() method to read messages
const messages = await thread.messages();
Create a new thread
Run the create-thread example script.
import type {
// ... previous imports
ThreadMemberScope,
} from '@dialectlabs/sdk';
const recipient = new PublicKey('3vuCFLbVWsNeWgyxkb2xiLQuxKDW83HWiTMmodT8gmtk') // Make this arbitrary
const command: CreateThreadCommand = {
encrypted: false,
me: {
scopes: [ThreadMemberScope.ADMIN, ThreadMemberScope.WRITE],
},
otherMembers: [
{
publicKey: recipient,
scopes: [ThreadMemberScope.ADMIN, ThreadMemberScope.WRITE],
},
],
};
// Uses the default backend.DialectCloud offchain. The command above may optionally take a preferred backend.
const thread = await sdk.threads.create(command);
Send a message
Run the send-message example script.
// ... code from previous examples
const text = 'gm world';
const command: SendMessageCommand = {
text,
}
await thread.send(command);
Delete a thread
Run the delete-thread example script.
const threadId = thread.id; // Keep for re-querying to confirm deletion
await thread.delete();
const query: FindThreadByIdQuery = {
id: threadId,
};
const refetchedThread = await sdk.threads.find(query); // Will be null
Dapp Notifications & Subscriptions
The following examples describe how to interact use the Dialect SDK to manage dapp and notification related resources.
Register a dapp
To allow users to subscribe to notifications from you, you first need to create a dapp in the Dialect API.
// Construct the SDK client from all of the above. Let's use 'development' for the environment, and pass
const environment = 'development';
const dialectCloud = {
// N.b. we omit the url value here, since 'development' will default to https://dev.dialectapi.to.
tokenStore: TokenStore.createInMemory(),
};
// Use ConfigProps values from example above.
const sdk: DialectSdk = Dialect.sdk({
backends,
dialectCloud,
environment,
encryptionKeysStore,
solana,
wallet,
} as ConfigProps);
// N.b. this created dapp is associated with the wallet public key connected to the sdk instance.
const dapp = await sdk.dapps.create({
name: 'My test dapp',
description: `My test dapp's description.`
});
Note that all dapps created with Dialect must be associated with a wallet keypair. This keypair will be used for all authenticated requests made for the dapp, and for all user messaging.
The sdk.dapps.create method above uses the wallet public key connected to the sdk client instance.
You can only create one dapp per public key.
Dapp whitelist
Dialect manages a list of verified dapps that have integrated with Dialect. While all messaging is done via wallets and keypairs and sent along the core messaging rails, this whitelist is convenient for surfacing just messages that are specifically from the most well-known dapps on Solana.
Whether or not this list continues to be maintained is to be determined.
If you'd like to be added to this list, please reach out to us on twitter or email us at [email protected].
Get your dapp
If the wallet you've connected to your sdk client instance is associated with a dapp, you can get the dapp record by making a simple find call.
const dapp = await sdk.dapps.find();
Get all dapps
You can query for all registered dapps in the the Dialect API DB.
const dapps = await sdk.dapps.findAll();
Fetch all whitelisted dapp messages for a given wallet
The Dialect SDK provides an endpoint for querying all messages from whitelisted dapps for a given wallet. This is convenient for producing a single feed of notifications.
// ... code from previous examples
const messages = await sdk.wallet.dappMessages.findAll({
dappVerified: true,
});