kukai-embed v0.9.2

Kukai-Embed

Kukai-Embed embeds a Kukai component instance into a page via an iFrame and exposes an API to the consuming application to interact with the Kukai instance. This allows applications to leverage the Tezos ecosystem in an convenient and user-friendly way without being concerned about wallets or key management.

Usage

⚠️ You can use kukai-embed on ghostnet for local development. However, if you intend to use kukai-embed on mainnet, your domain needs to be whitelisted. Send inquiries to contact@kukai.app.

Kukai-Embed is designed to provide a convenient interface for applications to interact with the Tezos blockchain ecosystem while also keeping users in control. The API provides an asynchronous wrapper for communication with a Kukai instance which manages the user's keys and accounts which applications can await while the user interacts with the Kukai UI.

Initialization

Kukai-Embed needs only to be constructed and initialized:

import { KukaiEmbed, Networks } from 'kukai-embed';

// construct the embed instance using mainnet (also the default value)
const embed = new KukaiEmbed({
    net: Networks.mainnet // requires domain whitelisting
});

// wait for the embedded Kukai instance to be initialized
await embed.init();

Login

Login presents a DirectAuth UI to the user and a promise to the application, which resolves with user account into when DirectAuth completes or rejects if the DirectAuth prompt is closed:

const userInfo = await embed.login();

UI & params

Providers can be added as loginOptions and their appearance can change with wideButtons:

const userInfo = await embed.login({
  loginOptions: ['google', 'facebook'],
  wideButtons: [true, false],
});

Additional auth params can be added as authParams, using an id and a nonce:

const userInfo = await embed.login({
    ...,
    authParams: { id: '<your id>', nonce: '<your nonce>' },
});

User Status

The embed persists the user's information on login and clears it on logout. It can be accessed from the .user field and will be null if a user is not logged in:

const userInfo = embed.user

Send Tezos Operations

Send allows an application to pass a Tezos Operation to the user for approval using the Kukai UI. The payload is compatible with @airgap/beacon-sdk (see operation request docs). The application can await the returned promise to recieve the operation hash of the operation when the user approves, or the rejection should they disapprove.

The following example demonstrates how to send 1 tez. Please note that the amount is specified in mutez, where 1,000,000 mutez equals 1 tez. The send promise resolves as soon as the operation is approved, at which point the operation hash is returned. However, if the operation is rejected, it throws an error. Kukai-embed does not track the on-chain success of outgoing operations:

const operationInfo = await embed.send([{
    kind: 'transaction',
    destination: 'tz1NBvY7qUedReRcYx8gqV34c8fUuks8o8Nr',
    amount: '1000000' // amount in mutez
}]);

If you intend to send an operation that includes a contract call, you can add a parameters field to the object above (see a full example of an entrypoint call):

    kind: 'transaction',
    // ...
    parameters: {
        entrypoint: 'set_color',
        value: {
            int: tokenId,
        },
    }

Authentication

Kukai-Embed can provide user authentication for applications based on their Tezos private key. authenticate takes an identifier for the authentication request and a challenge nonce to be signed. It returns a message which is created from the request and nonce, as well as a signature which is made using the returned message and the private key of the logged-in user. This signature can be verified using the message and the user's public key in order to prove authentication of the user.

const { message, signature } = await embed.authenticate('example request ID', 'example nonce')

Logout

Logout clears the Kukai instance of key information and returns it to a logged-out (but still initialized) state:

await embed.logout();

Examples

See the examples directory for simple examples of Kukai-Embed appearing in consuming applications.

Building

To build Kukai-Embed, use yarn build or npm run build.

Running unit tests

To run the unit tests, use yarn test or npm run test. Unit tests make use of Jest and JS-DOM.