@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

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.

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