npm package: @gloxx/nodejs
Description: Native Rust bindings for the Gloxx Network wallet
Latest version: 0.1.1

# @gloxx/nodejs

This package provides native Node.js bindings for the Gloxx network, implemented in Rust. It offers a high-performance and secure way to interact with the core functionalities of the Gloxx ecosystem—including wallet management, transaction creation, and cryptography—directly from your Node.js applications.

## Installation

```bash
npm install @gloxx/nodejs
```

The package uses `optionalDependencies` to automatically download the correct pre-compiled binary for your OS and architecture, so no manual compilation is needed.

## Quick Start: Creating and Signing a Transaction

Here’s how you can generate a wallet, create a transaction, and sign it.

```javascript
const {
    generateWallet,
    createTransaction,
    signTransaction,
} = require('@gloxx/nodejs');

try {
    // 1. Generate a new wallet for the sender
    const senderWallet = generateWallet();
    console.log('Sender Wallet:');
    console.log('  Address:', senderWallet.address);
    console.log('  Public Key:', senderWallet.publicKey);

    // 2. Define transaction details
    const recipientAddress = "glx1...recipient_address..."; // Replace with a real address
    const amount = 100n; // Use BigInt for amounts
    const nonce = 0n;    // Use BigInt for the nonce

    // 3. Create the transaction payload
    // This returns a Buffer containing the serialized, unsigned transaction
    const unsignedTxBuffer = createTransaction(
        senderWallet.address,
        senderWallet.publicKey,
        recipientAddress,
        amount,
        nonce
    );
    console.log('\nSuccessfully created unsigned transaction buffer.');

    // 4. Sign the transaction buffer with the sender's private key
    const signature = signTransaction(unsignedTxBuffer, senderWallet.privateKey);
    console.log('Transaction Signature:', signature);

    // The `unsignedTxBuffer` and `signature` can now be broadcast
    // to a Gloxx network node.

} catch (error) {
    console.error('Operation failed:', error);
}
```

## API Reference

All functions are synchronous and will throw an `Error` if the underlying native operation fails.

### Wallet Management

- `generateWallet()`
  - **Returns:** A `NativeWallet` object: `{ address: string, mnemonic: string, privateKey: string, publicKey: string }`.

- `importWallet(phrase, passphrase?)`
  - **Parameters:** `phrase` (string), `passphrase` (optional string).
  - **Returns:** A `NativeWallet` object.

### Transaction Workflow

- `createTransaction(senderAddress, publicKeyHex, recipientAddress, amount, nonce)`
  - **Description:** Constructs a serialized, unsigned transaction.
  - **Parameters:**
    - `senderAddress` (string): The sender's `glx1...` address.
    - `publicKeyHex` (string): The sender's hex-encoded public key.
    - `recipientAddress` (string): The recipient's `glx1...` address.
    - `amount` (bigint): The amount to transfer.
    - `nonce` (bigint): The sender's current transaction count.
  - **Returns:** (Buffer) A buffer containing the bincode-serialized transaction.

- `signTransaction(transactionBuffer, privateKeyHex)`
  - **Description:** Signs a transaction buffer created by `createTransaction`.
  - **Parameters:**
    - `transactionBuffer` (Buffer): The buffer returned from `createTransaction`.
    - `privateKeyHex` (string): The sender's hex-encoded private key.
  - **Returns:** (string) The resulting signature, hex-encoded.

### Other Cryptographic Functions

- `signMessage(message, privateKeyHex)`
  - **Parameters:** `message` (string | Buffer), `privateKeyHex` (string).
  - **Returns:** (string) The hex-encoded signature.

- `verifySignature(message, signatureHex, publicKeyHex)`
  - **Parameters:** `message` (string | Buffer), `signatureHex` (string), `publicKeyHex` (string).
  - **Returns:** (boolean) `true` if the signature is valid.

### Secure Keystore (Filesystem)

These functions allow you to encrypt and store keys on the server's local filesystem.

- `saveKeystore(privateKeyHex, address, password, path)`
  - Encrypts a private key and saves it to a JSON keystore file.

- `loadKeystore(address, password, path)`
  - Loads and decrypts a private key from a keystore file.

- `signMessageFromKeystore(message, address, password, path)`
  - A convenience function to load a key, sign a message, and return the signature.

## Cross-Platform Support

The `@gloxx/nodejs` package is designed to be cross-platform and supports the following targets:
- Linux: x64 (glibc and musl) and ARM64
- Windows: x64 (MSVC)
- macOS: Universal (x64 and Apple Silicon)

## License
MIT

© 2025 Gloxx Network