Skip to main content

WaaS SDK

The WaaS SDK is a client-side React Native library for participating in the MPC operations initiated on WaaS MPCKeyService.

Proxy-Mode vs. Direct-Mode​

Users can switch between two distinct operating modes: proxy-mode and direct-mode.

Proxy-mode allows the application to connect to the Coinbase WaaS API through a proxy server. The primary features of this mode include:

  • Initiate the SDK without needing the Coinbase Cloud API key details in the app itself. Communication will be authenticated during Proxy-Server <-> WaaS API.
  • The SDK, by default, points to a proxy server endpoint at localhost:8091. Update this proxyUrl in the config.json file.
  • Cloud credentials are stored in the proxy server, eliminating the need to have them on the application side.

Direct-Mode​

Direct-mode enables the app to connect directly to the Coinbase WaaS API, bypassing the need for a proxy server. Key aspects of this mode are:

  • The app communicates directly with the Coinbase WaaS API, with no involvement of a proxy server.
  • Users must provide the API Key and private key for communication, retrieved from the .coinbase_cloud_api_key.json file.

Essential APIs​

There are several essential APIs in the SDK, and they are generally called in the following order:

Summary​

Device Setup​

  1. initMPCSdk - Call first, before any other API is called.

  2. bootstrapDevice - Call once per device--subsequent calls are ignored. It accepts the passcode used to encrypt key material in the phone’s security module.

  3. getRegistrationData - Use the string returned by getRegistrationData to call RegisterDevice (MPCKeyService), which registers the device with WaaS servers.

  4. computeMPCOperation - Call to process the MPC operations returned from ListMPCOperations, e.g., for CreateDeviceGroup and CreateSignature.

Recovery​

  1. computePrepareDeviceArchiveMPCOperation - Call to process the MPC operations of type PrepareDeviceArchive returned from ListMPCOperations.

  2. exportPrivateKeys - Call to export the private keys corresponding to MPCKeys derived from a particular DeviceGroup.

  3. computePrepareDeviceBackupMPCOperation - Call to process the MPC operations of type PrepareDeviceBackup returned from ListMPCOperations.

  4. exportDeviceBackup - Call to export the device backup for a DeviceGroup.

  5. computeAddDeviceMPCOperation - Call to process the MPC operations of type AddDevice returned from ListMPCOperations.

Recovery Edge Cases​

  1. resetPasscode - Call to reset the passcode used to encrypt the backups and archives of the DeviceGroups containing this Device.
info

Additional APIs are provided in the SDK for convenience; but we don't recommend them. Instead, secure your application with a proxy server in between the device and WaaS servers for all API calls, including ListMPCOperations.

Device Setup​

1. initMPCSdk​

Initializes the MPC SDK. This function must be invoked before any MPC SDK methods are called.

  • @returns: A promise with the string "success" on successful initialization; a rejection otherwise.

2. bootstrapDevice​

Bootstraps the Device with the given passcode. The passcode is used to generate a private/public key pair that encodes the back-up material for WaaS keys created on this Device.

This function should be called exactly once per Device per application, and should be called before the Device is registered with getRegistrationData.

It is the responsibility of the application to track whether bootstrapDevice has been called for the Device.

  • @param passcode: Passcode to protect all key materials in the secure enclave.
  • @returns: A promise with the string "bootstrap complete" on successful initialization; a rejection otherwise.

3. getRegistrationData​

Retrieves the data required to call RegisterDevice on MPCKeyService.

  • @returns: A promise with the registrationData on success; a rejection otherwise.

4. computeMPCOperation​

Computes an MPCOperation, given mpcData from the response of ListMPCOperations API on MPCKeyService.

  • @param mpcData: The mpcData from ListMPCOperationsResponse on MPCKeyService.
  • @returns: A promise with the string "success" on successful MPC computation; a rejection otherwise.

Recovery​

5. computePrepareDeviceArchiveMPCOperation​

Computes a PrepareDeviceArchive MPCOperation, given mpcData from the response of ListMPCOperations API on MPCKeyService and passcode for the Device.

  • @param mpcData: The mpcData from ListMPCOperationsResponse on MPCKeyService.
  • @param passcode: The passcode set for the Device on BootstrapDevice call.
  • @returns: A promise with the string "success" on successful MPC computation; a rejection otherwise.

6. exportPrivateKeys​

Exports private keys corresponding to MPCKeys derived from a particular DeviceGroup. This method only supports exporting private keys that back EVM addresses. This function is recommended to be called while the Device is on airplane mode.

  • @param mpcKeyExportMetadata: The metadata to be used to export MPCKeys. This metadata is obtained from the response of GetDeviceGroup RPC in MPCKeyService. This metadata is a dynamic value, ensure you pass the most recent value of this metadata.
  • @param passcode: Passcode protecting key materials in the device, set during the call to BootstrapDevice.
  • @returns: A promise with the ExportPrivateKeysResponse on success; a rejection otherwise.

7. computePrepareDeviceBackupMPCOperation​

Computes a PrepareDeviceBackup MPCOperation, given mpcData from the response of ListMPCOperations API on MPCKeyService and passcode for the Device.

  • @param mpcData: The mpcData from ListMPCOperationsResponse on MPCKeyService.
  • @param passcode: The passcode set for the Device on BootstrapDevice call.
  • @returns: A promise with the string "success" on successful MPC computation; a rejection otherwise.

8. exportDeviceBackup​

Exports the device backup that is created after successfully computing a PrepareDeviceBackup MPCOperation. It is recommended to store this backup securely in a storage provider of your choice.

  • @returns: A promise with the backup as hex-encoded string; a rejection otherwise.

If the existing Device is lost, follow the below steps:

  1. Bootstrap the new Device with the same passcode as the old Device.
  2. Register the new Device.
  3. Initiate AddDevice MPCOperation using the AddDevice RPC in the MPCKeyService.
  4. Compute AddDevice MPCOperation with the computeAddDeviceMPCOperation method using this exported device backup.

9. computeAddDeviceMPCOperation​

Computes an AddDevice MPCOperation, given mpcData from the response of ListMPCOperations API on MPCKeyService and passcode for the Device.

  • @param mpcData: The mpcData from ListMPCOperationsResponse on MPCKeyService.
  • @param passcode: The passcode set for the Device on BootstrapDevice call.
  • @param deviceBackup: The backup retrieved from the exportDeviceBackup call after successful computation of a PrepareDeviceBackup MPCOperation.
  • @returns: A promise with the string "success" on successful MPC computation; a rejection otherwise.

Recovery Edge Cases​

10. resetPasscode​

Resets the passcode used to encrypt the backups and archives of the DeviceGroups containing this Device.

While there is no need to call bootstrapDevice again, it is the client's responsibility to call and participate in PrepareDeviceArchive and PrepareDeviceBackup operations afterwards for each DeviceGroup the Device was in. This function can be used when/if the end user forgets their old passcode.

  • @param newPasscode: The new passcode to use to encrypt backups and archives associated with the Device.
  • @returns: A promise with the string "passcode reset" on successful initialization, or a rejection otherwise.

Was this helpful?