Kinetic SDK developer experience

[beeman]

Kinetic SDK RFC

Abstract

The goal of this RFC is to get feedback from the ecosystem partners about the usage and terminology of the Kinetic SDKs.

We strive to build a uniform API interface that works between all the SDKs, regardless of the language/framework.

Deprecations

The goal of the new iteration of SDKs is that they provide very similar features as the current ones, and they should generally work the same.

That said, there are a few places where we will deviate. Most notable, the new APIs and SDKs won't include or support:

• Invoices
  • Invoices will be removed, but a developer will be able to provide a way to reference their transactions for integration with backend systems.
• The 'sign-transaction' webhook
  • Remote signing should not be needed when you are in control of your hot wallet.
  • The sign-transaction is replaced with a verify-transaction that allows you to accept or deny any transactions based on the metadata.
• UI Elements (Android/iOS)
  • The new SDKs don't ship any UI elements, it only delivers lower-level methods to integrate KIN.
  • If people in the community of ecosystem partners are interested in taking over maintenance of the current UI elements we are happy to collaborate on extracting those out into a separate repo maintained by members of our community.
  • To ensure recognition and consistency in the way people interact with Kin, the Kin Foundation will provide guidelines about usage of labels, logos, terminology, common patterns, etc., some of which might be required.
• Stellar-based keypairs
  • The new SDKs won't support the current keypairs out of the box. See the 'Generate Keypair' section below.

ℹ️ There might be more deprecations but these should be the most important ones. We will provide documentation on how to migrate from Agora SDKs to Kinetic SDKs.

Request for Comments

We are interested to hear your feedback on the methods below.

The SDK defined below is implemented in the @kinetic/sdk package (TypeScript) for you to play around with.

As a reference, you can look at the Kin 4 SDK Matrix to see what the current SDKs look like.

SDK methods

PublicKeyString

In some methods you'll see the type PublicKeyString being used. This is a convenience type that allows passing in as a PublicKey instance or a string. Where possible, a Kinetic SDK should provide this convenience type so developers can use both.

export type PublicKeyString = PublicKey | string

Initialize SDK

The initialization of the SDK is an asynchronous operation.

This is because the SDK will connect to the Kinetic API to retrieve the app configuration.

const sdk: KineticSdk = await KineticSdk.setup({
    // Select 'devnet' or 'mainnet
    environment: 'devnet',
    // The app index provided by the Kin Foundation
    index: 42,
    // Optional endpoint when self-hosting the Kinetic API
    endpoint: 'https://kinetic.my-app.com'
})

Generate Keypair

A new Keypair can be generated using the Keypair.random() method.

// Destructure the most frequently used properties for using on the device:
const { mnemonic, publicKey, secretKey } = Keypair.random();
// Or create an instance of `Keypair`:
const owner: Keypair = Keypair.randon()
// Get an instance of the `Keypair` based on the mnemonic:
const alice: Keypair = Keypair.fromMnemonic(alice.mnemonic)
// The instance will have a standard Solana keypair available as an object
customTransaction.sign({
  feePayer: alice.solana, // This is `Keypair` from `@solana/web3.js`
  source: alice.solana.publicKey, // This is the `PublicKey` from `@solana/web3.js`
})

This will generate a mnemonic phrase and derive a secret key with that, in a way that's compatible to standard Solana wallets (Glow, Phantom, Slope, Solflare, etc...)

The mnemonic phrase should be shared with the user, so they can create a backup. After onboarding and wallet creation, the user should be able to back up their wallet, in both cases using a similar flow like in the wallets mentioned above (write down words, make user verify they did it).

This way we will ensure compatibility with the larger Solana ecosystem, and create compatibility between the apps in the Kin ecosystem without having to build another custom backup/restore solution.

ℹ️ For existing apps, we will make sure there is an upgrade path for the current Stellar-based keypairs used by most SDKs.
However, this will be a compatibility library outside the Kinetic core. This way, greenfield apps don't have to carry around the (often dated) Stellar dependencies.
That said, the upgrade stately is beyond of the scope of this document and will be discussed elsewhere.

Create Account

This method is used to create the account for the account owner.

• Input
  • It takes the owners keypair and the commitment as input.
• Logic
  • It creates a "Create Account" transaction and signs it
  • It hands this transaction over to the API to co-sign it
• Output
  • Finally, the API returns the meta-data about the transaction

interface CreateAccountOptions {
  owner: Keypair
  commitment: SolanaCommitment
}

function createAccount(
    opts: CreateAccountOptions
): Promise<AppTransaction> {}

Get Balance

This method is used to get the balance of KIN.

• Input
  • It takes the accountId as input.
• Logic
  • The API fetches the KIN token accounts of the accountId
  • The API fetches the balance of any KIN token accounts found.
  • It sums the total account balance
• Output
  • The API returns the total account balance (see proposal below)

function getBalance({
  accountId: PublicKeyString
}): Promise<AccountBalance>

Proposal

The idea is to return a summary of how the balance came to be. We can return this data as we are already retrieving it.

So instead of returning only the single balance:

{ "balance": "42" }

We return something like this:

{
  // Return the balance of the default mint (KIN)
  "balance": "42",
  // Return the details of all the token accounts
  // Instead of `accounts` we could pick `tokens`
  "accounts": [
    { "accountId": "ABC...XYZ" "balance": "12", "mint": "kinX...HJq6" },
    { "accountId": "DEF...UVW" "balance": "30", "mint": "kinX...HJq6" },
  ],
  // Return the balance per mint
  "mints": {
	  "kinX...HJq6": "42"
  }
}

Resolve Token Accounts

This method is used to return the token accounts for the account owner.

ℹ️ This might be obsolete if we accept the proposal in the "Get Balance" section

• Input
  • It takes the accountId as input.
• Logic
  • The API fetches the KIN token accounts of the accountId
• Output
  • Finally, the API returns an array of token accounts

function resolveTokenAccounts(
    accountId: PublicKeyString
): Promise<string[]> {}

Make Transfer

This method is used to transfer an amount of KIN to a destination.

• Input
  • It takes the MakeTransferOptions as input.
• Logic
  • It creates a "Token Transfer" transaction and signs it
  • It hands this transaction over to the API to co-sign it
• Output
  • Finally, the API returns the meta-data about the transaction

interface MakeTransferOptions {
  owner: Keypair
  amount: string
  destination: PublicKeyString
}

function makeTransfer(
    opts: MakeTransferOptions
): Promise<AppTransaction> {}

Make Transfer Batch

This method is the same as the above, except that instead of sending 1 amount and destination, you can send it to multiple.

• Input
  • It takes the owners keypair and the commitment as input.
• Logic
  • It creates a MakeTransferBatchOptions transaction and signs it
  • It hands this transaction over to the API to co-sign it
• Output
  • Finally, the API returns the meta-data about the transaction

interface MakeTransferBatchOptions {
  owner: Keypair
  destinations: [
	{ account: PublicKeyString, amount: string },
  ]
}

function makeTransferBatch(
    opts: MakeTransferBatchOptions
): Promise<AppTransaction> {}

Request Airdrop

This method is used to request and airdrop of KIN on the Devnet.

• Input
  • It takes an accountId and amount
• Logic
  • It requests the API to airdrop the amount to the account
• Output
  • It returns the transaction signature

interface RequestAirdropOptions {
  accountId: PublicKeyString
  amount: string
}

function requestAirdrop(
    opts: RequestAirdropOptions
): Promise<TransactionSignature> {}

Merge Token Accounts

This method merges multiple token accounts.

It will be tracked as a separate issue on GitHub:

#204