Skip to main content

Getting started

Katavault can be started simply with a few lines of code.

Overview​

The core implementation contains the main functionality that handles all the authentication, encryption and storage of wallet keys.

Quick start​

1. Set up Katavault​

Configure the Katavault client.

info

While not a requirement, it is RECOMMENDED to use @kibisis/chains to handle the chain configuration.

import { voi } from '@kibisis/chains';
import { createKatavault } from '@kibisis/katavault-core';

const katavault = await createKatavault({
  chains: [voi],
});
note

See CreateKatavaultParameters for information on the available parameters.

2. Authentication​

Katavault currently supports two types of encryption:

  • Web Authentication (WebAuthn) — utilizing the PRF extension to extract encryption key material that can be used with strong AES-GCM data encryption.
  • Password — more traditional, but more widely supported.

The choice of authentication method comes down to either support or to the prerogative of the integration.

note

Authentication using one of the below methods is REQUIRED for all interactions with sensitive (private keys) information — including write operations, such as signing.

2.1. Passkey authentication​

await katavault.authenticateWithPasskey({
  user: {
    displayName: 'Kibi', // optional
    username: 'kibi@kibis.is',
  },
});

console.log(`is authenticated: ${katavault.isAuthenticated()}`);
/*
is authenticated: true
*/
note

See AuthenticateWithPasskeyParameters for information on the available parameters.

If this is the first time the user has used Katavault, they will be prompted to "register" a passkey. Under the hood, this is essentially calling navigator.credentials.create().

Once the user has successfully registered the passkey, they will need to "authenticate" the passkey to extract the key material, which is used to derive an encryption key. Similar to above, under the hood this is essentially calling navigator.credentials.get().

warning

If passkeys are not supported, or the supplied passkey does not support the PRF extension, a PasskeyNotSupportedError error will be thrown.

2.2. Password authentication​

await katavault.authenticateWithPassword({
  password: 'mtr*tpv!cbg@dhn9RFH',
  user: {
    displayName: 'Kibi', // optional
    username: 'kibi@kibis.is',
  },
});

console.log(`is authenticated: ${katavault.isAuthenticated()}`);
/*
is authenticated: true
*/
note

If Katavault was previously initialized with a password, and the supplied password does not match the saved one a InvalidPasswordError error will be thrown.

note

See AuthenticateWithPasswordParameters for information on the available parameters.

3. Using Katavault​

Once the client is set up and authenticated, you can start interacting with the embedded wallet.

const account = await katavault.generateAccount('Personal');

console.log(account);
/*
{
  address: 'SH2KEL633QIJLURBOOJTIKR5EIIYR4A2VYZC2DB6ZD4ZZL6XHYFBETEOGU',
  name: 'Personal',
}
*/