npm package: @gloxx/gloxx-wasm
Description: WebAssembly (Wasm) bindings for the Gloxx Network, providing high-performance cryptographic operations and wallet management for browser-based environments.
Latest version: 0.1.1

# @gloxx/wasm

WebAssembly (Wasm) bindings for the Gloxx Network, providing high-performance cryptographic operations and wallet management for browser-based environments.

## Overview

This package brings the security and performance of the Gloxx Rust implementation to the web. It allows developers to build client-side applications that can:
- Create and manage user wallets.
- Construct valid Gloxx transactions.
- Cryptographically sign transactions and messages.

All of this is done in a secure, client-side context without relying on centralized servers for sensitive operations.

## Installation

```bash
npm install @gloxx/wasm
```

## Quick Start: Creating and Signing a Transaction

Since this package is built with `--target web`, you must initialize the Wasm module before using any functions.

```javascript
import init, {
    generate_wallet,
    create_transaction,
    sign_transaction
} from '@gloxx/wasm';

async function main() {
    // 1. Load the Wasm binary
    await init();

    try {
        // 2. Create a new wallet
        const senderWallet = generate_wallet();
        console.log(`Sender Address: ${senderWallet.address}`);

        // 3. Define transaction details
        const recipientAddress = "glx1...recipient_address..."; // Replace with a real address
        const amount = 100; // The amount to send
        const nonce = 0;    // The sender's current nonce

        // 4. Create the transaction object
        // This object is a JsValue, an opaque handle to the Rust struct.
        // It is not a plain JavaScript object.
        const unsignedTx = create_transaction(
            senderWallet.address,
            senderWallet.public_key,
            recipientAddress,
            amount,
            nonce
        );
        console.log("Successfully created transaction object.");

        // 5. Sign the transaction object using the sender's private key
        const signature = sign_transaction(unsignedTx, senderWallet.private_key);
        console.log(`Transaction Signature: ${signature}`);

        // The `unsignedTx` object and the `signature` can now be broadcast
        // to a Gloxx network node using a library like fetch or axios.

    } catch (error) {
        console.error("Gloxx Wasm Error:", error);
    }
}

main();
```

## API Reference

All functions return a `Promise` if using an async bundler or require an `await init()` call first.

### Wallet Management

- `generate_wallet()`: Generates a new random wallet. 
  - **Returns:** `JsWallet` object: `{ address, mnemonic, private_key, public_key }`.

- `import_wallet(phrase, passphrase?)`: Recovers a wallet from a mnemonic phrase. 
  - **Parameters:**
    - `phrase` (string): The 12-24 word recovery phrase.
    - `passphrase` (optional string): An optional BIP39 passphrase.
  - **Returns:** `JsWallet` object.

### Transaction Workflow

- `create_transaction(sender_address, public_key_hex, recipient_address, amount, nonce)`: Constructs an unsigned transaction.
  - **Parameters:**
    - `sender_address` (string): The sender's `glx1...` address.
    - `public_key_hex` (string): The sender's public key, hex-encoded.
    - `recipient_address` (string): The recipient's `glx1...` address.
    - `amount` (number): The amount of the transfer.
    - `nonce` (number): The sender's current transaction count.
  - **Returns:** `JsValue` - An opaque handle to the Rust transaction object. Pass this directly to `sign_transaction`.

- `sign_transaction(transaction_js, private_key_hex)`: Signs a transaction object created by `create_transaction`.
  - **Parameters:**
    - `transaction_js` (JsValue): The object returned from `create_transaction`.
    - `private_key_hex` (string): The sender's private key, hex-encoded.
  - **Returns:** (string) The resulting signature, hex-encoded.

### Other Cryptographic Functions

- `sign_message(message, private_key_hex)`: Signs a generic message (string or `Uint8Array`).
- `verify_signature(message, signature_hex, public_key_hex)`: Validates a signature against a public key. Returns `true` if valid.
- `encrypt_keystore(private_key_hex, address, password)`: Encrypts the private key, returning a JSON string for secure storage (e.g., in `localStorage`).

## License

MIT

© 2025 Gloxx Network