@portal-hq/eject-js

A JavaScript library for recovering private keys from distributed key generation (DKG) results, supporting both secp256k1 and ed25519 curves.

Overview

@portal-hq/eject-js provides functionality to recover private keys from distributed key generation results. It's designed to work with 2-of-2 threshold schemes where key shares are distributed between a client and a server. The library supports both secp256k1 (commonly used in Bitcoin and Ethereum) and ed25519 (used in many modern cryptographic systems) elliptic curves.

Features

• Recover private keys from distributed key generation results
• Support for both secp256k1 and ed25519 curves
• Handle various input formats (string, object, Uint8Array)
• Validate and format shares
• Perform necessary matrix operations for key recovery
• Convert between different formats (BigInt, Uint8Array, hex strings)
• Base58 encoding support for ed25519 keys

Installation

npm install @portal-hq/eject-js

Usage

Basic Usage

const ejectJs = require('@portal-hq/eject-js');

// Gather the client and server backup shares
const secp256k1ClientShare = { /* ... client SECP256K1 DKG data ... */ };
const ed25519ClientShare = { /* ... client ED25519 DKG data ... */ };

const secp256k1ServerShare = { /* ... server SECP256K1 DKG data ... */ };
const ed25519ServerShare = { /* ... server ED25519 DKG data ... */ };

// Recover a secp256k1 private key
async function recoverSecp256k1Example() {
  try {
    const privateKey = await ejectJs.recoverSecp256k1Key(secp256k1ClientShare, secp256k1ServerShare);
    console.log('Recovered secp256k1 private key:', privateKey);
  } catch (error) {
    console.error('Error recovering private key:', error.message);
  }
}

// Recover an ed25519 private key
async function recoverEd25519Example() {
  try {
    const privateKey = await ejectJs.recoverEd25519Key(ed25519ClientShare, ed25519ServerShare);
    console.log('Recovered ed25519 private key (Base58):', privateKey);
  } catch (error) {
    console.error('Error recovering private key:', error.message);
  }
}

recoverSecp256k1Example();
recoverEd25519Example();

Advanced Usage

For more control over the recovery process, you can use the recoverAndFormatPrivateKey function:

const ejectJs = require('@portal-hq/eject-js');

async function advancedRecoveryExample() {
  try {
    const privateKey = await ejectJs.recoverAndFormatPrivateKey(
      clientDkgResult,
      serverDkgResult,
      {
        curve: 'secp256k1', // or 'ed25519'
        littleEndian: false // Set to true for little endian format
      }
    );
    console.log('Recovered private key:', privateKey);
  } catch (error) {
    console.error('Error recovering private key:', error.message);
  }
}

Input Formats

The library accepts DKG results in various formats:

• JSON strings
• JavaScript objects
• Uint8Array instances

Expected DKG Result Structure

For client DKG results, the library expects an object with the following structure:

{
  pubkey: {
    x: "x-coordinate as string",
    y: "y-coordinate as string"
  },
  share: "share value as string",
  bks: {
    server: {
      x: "x value as string",
      rank: 0
    }
  }
}

For server DKG results (CGGMP backup format), the library expects:

{
  clientId: "client identifier",
  custodianId: "custodian identifier",
  x: "public key x-coordinate",
  y: "public key y-coordinate",
  clientBk: "client Birkhoff parameter",
  serverBk: "server Birkhoff parameter",
  share: "share value",
  clientPartialPubKey_x: "client partial public key x-coordinate",
  clientPartialPubKey_y: "client partial public key y-coordinate",
  serverPartialPubKey_x: "server partial public key x-coordinate",
  serverPartialPubKey_y: "server partial public key y-coordinate",
  yClient_x: "client Y x-coordinate",
  yClient_y: "client Y y-coordinate",
  yServer_x: "server Y x-coordinate",
  yServer_y: "server Y y-coordinate",
  pailler_p: "Pailler P value",
  pailler_q: "Pailler Q value",
  ssid: "session ID",
  pedersenClient_n: "client Pedersen n value",
  pedersenClient_s: "client Pedersen s value",
  pedersenClient_t: "client Pedersen t value",
  pedersenServer_n: "server Pedersen n value",
  pedersenServer_s: "server Pedersen s value",
  pedersenServer_t: "server Pedersen t value"
}

API Reference

Main Functions

recoverAndFormatPrivateKey(clientDkgResult, serverDkgResult, options)

Recovers and formats a private key from DKG results.

• Parameters:
  • clientDkgResult: Client DKG result (string, object, or Uint8Array)
  • serverDkgResult: Server DKG result (string, object, or Uint8Array)
  • options: (Optional) Configuration object
    • curve: Curve to use ('secp256k1' or 'ed25519', default: 'secp256k1')
    • littleEndian: Whether to return in little endian format (default: false)
• Returns: Promise resolving to the recovered private key in hex format

recoverSecp256k1Key(clientDkgResult, serverDkgResult, littleEndian)

Convenience function for recovering a secp256k1 key.

• Parameters:
  • clientDkgResult: Client DKG result
  • serverDkgResult: Server DKG result
  • littleEndian: (Optional) Whether to return in little endian format (default: false)
• Returns: Promise resolving to the recovered private key in hex format

recoverEd25519Key(clientDkgResult, serverDkgResult, littleEndian)

Convenience function for recovering an ED25519 key.

• Parameters:
  • clientDkgResult: Client DKG result
  • serverDkgResult: Server DKG result
  • littleEndian: (Optional) Whether to return in little endian format (default: true)
• Returns: Promise resolving to the recovered private key in Base58 format

Helper Classes

The library also exports several helper classes for constructing inputs:

• AuxInfo: Class for auxiliary information for key recovery
• CggmpBackup: Class for CGGMP backup data
• Pubkey: Class representing a public key
• BK: Class representing a Birkhoff parameter

Dependencies

• noble-secp256k1: For secp256k1 curve operations
• elliptic: For curve operations
• bs58: For Base58 encoding (used with ed25519 keys)