@trilitech-umami/umami-embed

Umami Embed - WIP, not ready for production use

Umami-Embed is a component designed to integrate an instance of Umami Wallet into a webpage through an iFrame. It securely encapsulates user details and offers an API for the host application to interact with the Tezos blockchain.

Umami-Embed allows users to engage with decentralized applications (dApps) directly, eliminating the requirement for a separate wallet application.

For the demo implementation and more information, please visit the Umami-Embed Github repository.

Network Access

• ghostnet - available for anyone to use.
• mainnet - requires allowlisting. Please contact us at [e-mail] to get your domain added to the allowlist for mainnet access.

Supported Features

Methods are expected to be called in a synchronized manner. Each operation must be completed before another can be initiated.

Each method returns a promise that resolves upon successful completion or fails with error details if something goes wrong.

Public user data is stored in local storage to prevent the need for unnecessary re-logins. Logout removes the stored data.

Workflow

Initialization / Deinitialization

Set up or tear down the Umami-Embed environment.

The initialization step is required before any other method can be called.

If the user has logged in previously and their data is saved in local storage, it will be retrieved at this step.

On init, UmamiEmbedConfig can be applied. It includes the following parameters:

• network - required, either mainnet or ghostnet.
• iframeParent - optional HTMLElement to attach the iFrame to. Defaults to document.body.
• useLocalEmbedIframe - false by default. When true, it looks for an iframe at http://localhost:5173/ (works on ghostnet only).
• loginOptions - defaults to including all login types. You can specify an array with any of these options: google, reddit, twitter, facebook.
• theme - light by default. Supports light and dark options.
• logsLevel - none by default. Can be set to none, info, warn, error.

Check types.ts for more information about supported values.

Example

const umami = new UmamiEmbed();

const config: UmamiEmbedConfig = { network: 'ghostnet' };
await umami.init(config);

// prints true
console.log(umami.isInitialized);

// prints user data if saved in local storage
if (umami.isLoggedIn) {
    console.log(umami.user);
}

umami.destroy();

Login / Logout

Authenticate users through selected supported social logins.

login() returns user information upon successful execution.

If user data is present in local storage, it can be accessed by calling user property. The property will be null otherwise.

Example

const umami = new UmamiEmbed();
await umami.init({ network: 'ghostnet' });

if (umami.isLoggedIn) {
    const userData = umami.user;
    await umami.logout();
} else {
    const userData = await umami.login();
    console.log(userData);
}

Sending Tezos Operations

Send a list of Tezos operations for user approval. If user is not logged in, this method will throw an error.

Before displaying the confirmation modal, Umami Embed validates the operation and precomputes the fee. If the computation fails, the promise will resolve with an error. Otherwise, the confirmation modal will be displayed to the user.

Please note that the computation process may take some time. It is recommended to provide feedback to the user indicating that the operation has started, as nothing will be shown on our side until the computation completes.

Operations must be provided in PartialTezosOperation format. Refer to @airgap/beacon-sdk and the operation request doc for more details.

send() returns operation hash if the operation submission is successful.

Example

const umami = new UmamiEmbed();
await umami.init({ network: 'ghostnet' });
await umami.login();

umamiEmbed.send([ { "kind" : "transaction", "destination" : "tz1...", "amount" : "1000" } ]);

Signing Payload

Send a payload for user to sign. If user is not logged in, this method will throw an error.

This method allows users to approve and sign arbitrary data from a decentralized application.

sign() returns the signature of the payload after the user approves it through the confirmation modal. If user declines singing, the method will throw an error.

The payload can be signed using different signing types, such as RAW, OPERATION, or MICHELINE.

Example

const umami = new UmamiEmbed();
await umami.init({ network: 'ghostnet' });
await umami.login();

const payload = 'some-payload-data';  // This could be any payload you want to sign
const signature = await umami.sign(SigningType.RAW, payload);

License

This project is licensed under the MIT License. For more details, please visit the LICENSE file.