npm package: @getlea/keygen
Description: A CLI tool for generating Lea Chain keysets.
Author: Allwin Ketnawang
Latest version: 1.0.1

<!--
giturl: https://github.com/LEA-Blockchain/keygen
name: lea-keygen
version: 1.0.0
description: A CLI tool for generating Lea Chain keysets.
-->

[![npm version](https://img.shields.io/npm/v/@leachain/keygen)](https://www.npmjs.com/package/@leachain/keygen)
[![GitHub license](https://img.shields.io/github/license/LEA-Blockchain/keygen)](https://github.com/LEA-Blockchain/keygen/blob/main/LICENSE)

# `lea-keygen` Command-Line Usage

This guide provides detailed instructions for using the `lea-keygen` command-line tool to generate Lea Chain keysets.

## Installation

For one-off commands, you can use `npx` without any installation:

```sh
npx @leachain/keygen <command>
```

Alternatively, you can install it globally to use the `lea-keygen` command directly:

```sh
npm install -g @leachain/keygen
lea-keygen <command>
```

---

## Command Reference

The `lea-keygen` tool supports two main commands: `new` and `verify`.

### `new`

Generates a new keyset.

#### Synopsis

```sh
lea-keygen new [options]
```

#### Options

-   `--no-outfile`: Prints the generated keyset to standard output (`stdout`) as a JSON array instead of saving it to a file.
-   `--outfile <path>`: Specifies a custom file path to save the keyset. If this is not provided, the keyset is saved to `<address>.json` in the current directory.
-   `--force`: If a keyset file already exists at the target path, this flag allows overwriting it. Without this flag, the tool will exit with an error to prevent accidental data loss.
-   `--seed <hex>`: Generates a keyset deterministically from a 32-byte (64-character) hexadecimal master seed. This is useful for recovering a keyset from a single, high-entropy source.

#### Examples

##### 1. Generate a Keyset and Save to a File

This is the default behavior. It generates a new keyset and saves it to a file named after the derived public address.

**Command:**
```sh
npx @leachain/keygen new
```

**Output (to stderr):**
```
Public Address (bech32m): lea1q...
Public Address (hex):     ...
Keyset saved to: /path/to/project/lea1q....json
```

The resulting file will contain the full keyset with secure file permissions (`600`).

##### 2. Generate a Keyset from a Seed

Use the `--seed` flag to generate a keyset from a 32-byte hex string. This allows for deterministic key creation.

**Command:**
```sh
npx @leachain/keygen new --seed 11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff
```

##### 3. Generate a Keyset and Print to Console

Use the `--no-outfile` flag to prevent writing to a file and instead print the keyset to `stdout`.

**Command:**
```sh
npx @leachain/keygen new --no-outfile
```

**Output (to stdout):**
```json
[
  [
    [ ... private key ... ],
    [ ... public key ... ]
  ],
  [
    [ ... private key ... ],
    [ ... public key ... ]
  ]
]
```
**Output (to stderr):**
```
Public Address (bech32m): lea1q...
Public Address (hex):     ...
Keyset generated to stdout.
```

---

### `verify`

Displays the public address for a given keyset file.

#### Synopsis

```sh
lea-keygen verify <file_path>
```

-   `<file_path>`: The path to the keyset JSON file.

#### Description

This command reads a keyset file, derives the public address from it, and prints the address to standard output. This is useful for verifying the address of a wallet without needing to generate a new key.

#### Example

**Command:**
```sh
npx @leachain/keygen verify ./my-keys/main-wallet.json
```

**Output (to stdout):**
```
Address (bech32m): lea1q...
Address (hex):     ...
```

---

## Module Usage

In addition to the CLI, you can use `@leachain/keygen` as a library in your Node.js applications.

### Installation

```sh
npm install @leachain/keygen
```

### Examples

#### 1. Generate a Random Keyset

```javascript
const { generateKeyset } = require('@leachain/keygen');

async function createNewWallet() {
    try {
        const { keyset, address, addressHex } = await generateKeyset();
        console.log('New Keyset:', keyset);
        console.log('Public Address (bech32m):', address);
        console.log('Public Address (hex):', addressHex);
    } catch (error) {
        console.error('Failed to generate keyset:', error);
    }
}

createNewWallet();
```

#### 2. Generate a Keyset from a Master Seed

For deterministic key generation, provide a 32-byte `Buffer` as the master seed.

```javascript
const { generateKeyset } = require('@leachain/keygen');
const crypto = require('crypto');

async function createDeterministicWallet() {
    try {
        // IMPORTANT: Use a cryptographically secure, high-entropy seed.
        const masterSeed = crypto.createHash('sha256').update('a very secret phrase').digest();

        const { keyset, address } = await generateKeyset(masterSeed);
        console.log('Generated Address:', address);
        // You can now save or use the keyset.
    } catch (error) {
        console.error('Failed to generate deterministic keyset:', error);
    }
}

createDeterministicWallet();
```

#### 3. Usage with ES Modules (`import`)

The package also supports ES Module syntax.

```javascript
import { generateKeyset } from '@leachain/keygen';
import crypto from 'crypto';

async function createDeterministicWallet() {
    try {
        // IMPORTANT: Use a cryptographically secure, high-entropy seed.
        const masterSeed = crypto.createHash('sha256').update('a very secret phrase').digest();

        const { keyset, address } = await generateKeyset(masterSeed);
        console.log('Generated Address:', address);
    } catch (error) {
        console.error('Failed to generate deterministic keyset:', error);
    }
}

createDeterministicWallet();
```

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.