@fordefi/web-sdk

Fordefi Web SDK

Build

yarn install
yarn build

# serve demo page
yarn serve

Installation

Add to your HTML <head> section

<script src="https://apis.google.com/js/api.js"></script>
<script src="https://accounts.google.com/gsi/client"></script>
<script src="https://fordefi-sdk.s3.amazonaws.com/web-sdk@1.3.3/index.bundle.js"></script>

Usage

Onboard a new user

The following steps should first be done by an API user. Snippets with the following curl requests are also available at scripts/api-user-actions.sh.

1. Create a new user.

curl -X POST 'https://api.fordefi.com/api/v1/end-users' \
--data '{ "external_id": "John Doe" }' \
-H 'Authorization: Bearer xxxxx' \
-H 'Content-Type: application/json'

# response
{
  "id": "35afc2ab-d78e-442c-9582-8b314f927673",
  "created_at": "2024-02-29T02:08:02.319000Z",
  "modified_at": "2024-02-29T02:08:02.319000Z",
  "external_id": "John Doe",
  "last_login_at": "1970-01-01T00:00:00Z"
}

2. Issue an auth token on behalf of the user.

curl -X POST 'https://api.fordefi.com/api/v1/authorization-tokens' \
--data '{ "user_type": "end_user", "user_id": "35afc2ab-d78e-442c-9582-8b314f927673" }' \
-H 'Authorization: Bearer xxxxx' \
-H 'Content-Type: application/json'

# response
{
  "id": "3fa0fdfc-5991-455f-a109-f10a30fae6f6",
  "created_at": "1970-01-01T00:00:00Z",
  "modified_at": "1970-01-01T00:00:00Z",
  "user_id": "35afc2ab-d78e-442c-9582-8b314f927673",
  "expired_at": "2024-03-01T02:17:25.954667Z",
  "user_type": "end_user",
  "access_token": "eyJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

3. Enable a user to export their private keys (optional).

curl -X PUT 'https://api.fordefi.com/api/v1/end-users/35afc2ab-d78e-442c-9582-8b314f927673/set-export-end-user-keys-permissions' \
--data '{ "allow": true }' \
-H 'Authorization: Bearer xxxxx' \
-H 'Content-Type: application/json'

Initialize an SDK instance

const fordefiApiBaseUrl = "https://api.fordefi.com";

const fordefi = fordefiWebSDK.Fordefi.getInstance({
  baseURL: fordefiApiBaseUrl,
});

class SDKLogger {
  log(logLevel, message) {
    console.log(`[Fordefi SDK][${logLevel}] ${message}`);
  }
}
fordefi.setLogger(new MyLogger());

class ErrorHandler {
  handleError(error) {
    console.log('Error on Fordefi SDK', error.details);

    switch (error.errorCode) {
      case fordefiWebSDK.FordefiErrorCode.ExpiredAuthToken:
        // do something...
      case fordefiWebSDK.FordefiErrorCode.KeysRecoveryIsNeeded:
        // do something else...
    }
  }
}
fordefi.setErrorHandler(new ErrorHandler());

Login to the SDK

A user auth token should be issued by an API user on behalf of the user, and passed to the login() method. Check the device state in the result to act accordingly.

const { userID, deviceState } = await fordefi.login(userAuthToken);

if (deviceState === DeviceState.DeviceStateBackupRequired) {
   await fordefiSdk.backupKeys(backupOption)
} else if (deviceState === DeviceState.DeviceStateRecoveryRequired) {
   await fordefiSdk.recoverKeys(backupOption)
} else if (deviceState === DeviceState.DeviceStateError) {
   console.error('Device is in error state.')
} else if (deviceState === DeviceState.NoOperationRequired) {
   console.log('Device is provisioned and ready to sign transactions.')
}

Backup & Recover

Select a backup option:

Back up to Google Drive

// initialize the provider with Google Drive credentials
await fordefiWebSDK.FordefiBackupCloudProviders.getInstance().initialize({
  googleDrive: {
    // get credentials from Google Cloud Console (https://console.cloud.google.com/)
    clientID: "xxxxx",
    apiKey: "xxxxx",
  }
});

// use the Google Drive backup option
const backupOption = {
  type: fordefiWebSDK.FordefiBackupOptionType.CloudProvider,
  provider: fordefiWebSDK.FordefiBackupCloudProvider.GoogleDrive
};

// execute
await fordefi.backupKeys(backupOption);
await fordefi.recoverKeys(backupOption);

Back up an encrypted copy of the keys on the Fordefi platform

// initialize the provider
await fordefiWebSDK.FordefiBackupCloudProviders.getInstance().initialize();

// use the encryption key backup option.
// pass the symmetric key to encrypt (when creating a backup) or decrypt (when recovering from a backup) the user's key shares.
const backupOption = {
  type: fordefiWebSDK.FordefiBackupOptionType.ExternalEncryption,
  encryption: {
    // symmetric key to encrypt/decrypt the backup, generated and stored by the frontend app or its backend
    key: "xxxxx",
    type: fordefiWebSDK.FordefiExternalEncryptionKeyType.AES256
  }
}

// execute
await fordefi.backupKeys(backupOption);
await fordefi.recoverKeys(backupOption);

Export

Export the user's private keys. There are two requirements for users to be able to export their keys:

An API user must enable this user to export keys.
User's key shares are provisioned on the current device, otherwise the user should first go through the recovery process.

const { vaults } = await fordefi.exportKeys();
const { vault_id, private_key_hex, address } = vaults[0];

Signing a transaction

Given a transaction that was created by an API user the user signs the transaction

await fordefi.signTransaction(transactionId);