Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openhive-network/wax/llms.txt

Use this file to discover all available pages before exploring further.

​
Dual-language design

WAX provides Hive blockchain protocol features to both Python and TypeScript/JavaScript through a shared C++ core. This architecture allows you to work with the same blockchain functionality in your preferred language while maintaining consistency and performance.

​
Language bindings

​
TypeScript/JavaScript

The TypeScript implementation uses WebAssembly (WASM) compiled from C++ via Emscripten:
  • Package: @hiveio/wax published to npm
  • Location: ts/wasm/lib/ in the source tree
  • Build target: WASM artifacts in ts/wasm/build_wasm/
  • Design principle: Minimal bundle size for web applications
import { createWaxFoundation, createHiveChain } from "@hiveio/wax";

// Offline operations (transaction building, signing, validation)
const wax = await createWaxFoundation();

// Online operations (API calls, broadcasting)
const chain = await createHiveChain();

​
Python

The Python implementation uses Cython bindings compiled to native .so modules:
  • Package: hiveio-wax published to PyPI
  • Location: python/wax/ in the source tree
  • Bridge: cpp_python_bridge.pyx provides Cython bindings
  • Requirements: Python 3.14+
from wax import create_wax_foundation, create_hive_chain

# Offline operations
wax = create_wax_foundation()

# Online operations
chain = create_hive_chain()

​
C++ core

The core/ subdirectory contains the common C++ implementation shared by both language bindings:

​
Key components

class foundation {
public:
  std::string cpp_calculate_public_key(const std::string& wif);
  std::string cpp_generate_private_key();
  private_key_data cpp_generate_private_key(
    const std::string& account,
    const std::string& role,
    const std::string& password
  );
  // Transaction operations
  // Signing operations
  // Validation operations
};

​
Core files

FilePurpose
foundation.cpp/hppCore transaction and cryptographic operations
api_converter.hppConverts between API JSON and protocol buffers
proto_converter.hppProtocol buffer conversion utilities
signing_keys_collector.cpp/hppExtracts required signing keys from transactions
binary_view_helper.cpp/hppBinary serialization metadata
operations_fwd.hppForward declarations for all operations
val_protocol.hppValidation rules for protocol operations

​
Protocol buffers

WAX uses Protocol Buffers (protobuf) as the canonical format for representing blockchain operations and types. These definitions come from the Hive blockchain source in the hive/ submodule: Source location: hive/libraries/protocol/proto/

​
Generation process

1

TypeScript generation

Protocol buffers are compiled to TypeScript using ts-proto:
# Output location
ts/wasm/lib/proto/

# Pattern tracking
ts/protobuf_patterns/
2

Python generation

Protocol buffers are compiled to Python using grpcio-tools:
# Output location
python/wax/_private/proto/

# Pattern tracking
python/protobuf_patterns/

​
Example operation definitions

export interface transfer {
  from: string;
  to: string;
  amount: asset | undefined;
  memo: string;
}

​
Entry points

Both language implementations provide two main entry points that separate offline and online functionality:

​
Offline operations (Foundation)

import { createWaxFoundation } from "@hiveio/wax";

const wax = await createWaxFoundation();

// Available operations:
// - Transaction building
// - Transaction signing
// - Transaction validation
// - Cryptographic operations
// - No network calls
Implementation:
  • TypeScript: ts/wasm/lib/detailed/base.ts
  • Python: python/wax/wax_factory.py

​
Online operations (Chain)

import { createHiveChain } from "@hiveio/wax";

const chain = await createHiveChain({
  apiEndpoint: "https://api.hive.blog",
  restApiEndpoint: "https://api.syncad.com"
});

// Includes all Foundation operations plus:
// - API calls to Hive nodes
// - Transaction broadcasting
// - Account queries
// - Block retrieval
Implementation:
  • TypeScript: ts/wasm/lib/detailed/chain.ts
  • Python: python/wax/_private/chain_api.py

​
Project structure

The repository is organized to maintain separation between language implementations while sharing the core: 
wax/
├── core/                    # Shared C++ implementation
│   ├── foundation.cpp/hpp   # Core operations
│   ├── api_converter.hpp    # JSON ↔ Proto conversion
│   └── signing_keys_collector.cpp/hpp
│
├── hive/                    # Git submodule (Hive blockchain)
│   └── libraries/protocol/proto/  # Protocol definitions
│
├── ts/                      # TypeScript implementation
│   ├── wasm/lib/detailed/   # Core implementation
│   │   ├── base.ts          # createWaxFoundation()
│   │   ├── chain.ts         # createHiveChain()
│   │   ├── transaction.ts   # Transaction class
│   │   └── api/             # API type definitions
│   └── packages/            # Extension packages (signers)
│
└── python/                  # Python implementation
    └── wax/
        ├── wax_factory.py           # Entry points
        ├── cpp_python_bridge.pyx    # Cython bindings
        └── _private/
            ├── transaction.py       # Transaction class
            └── api/                 # API implementation

​
Build process

​
TypeScript

1

Compile protobuf definitions

# Generate TypeScript types from .proto files
ts-proto → ts/wasm/lib/proto/
2

Compile C++ to WASM

# Use Emscripten to compile C++ core
emcc → ts/wasm/build_wasm/
3

Build TypeScript

pnpm run build
# Compiles TS and bundles with WASM

​
Python

1

Compile protobuf definitions

# Generate Python types from .proto files
grpcio-tools → python/wax/_private/proto/
2

Compile Cython bindings

# Build native extension modules
cython → .so files
3

Build wheel

./python/wax/scripts/build_wax.sh
# Creates distributable wheel

​
Performance characteristics

TypeScript/WASM

  • Near-native performance in browsers
  • Small bundle size (optimized for web)
  • Instant startup
  • Memory-efficient

Python/Cython

  • Native C++ performance
  • Direct memory access
  • Minimal overhead
  • Ideal for server applications

​
Next steps

Transactions

Learn how transactions work in WAX

Operations

Understand operations and protocol buffers

Signing

Explore transaction signing and wallets

Quickstart

Build your first application

Build docs developers (and LLMs) love

Get started for freeTalk to us