Hive Bytecode (.hbc): format & manifest
Hive Bytecode (.hbc) is the module format HiveKit produces and NDSR executes. Under the hood a .hbc
is a ZIP archive with exactly two entries: manifest.json and module.wasm (the compiled code, a
WebAssembly binary restricted to the Hive Bytecode ABI hive-wasm-v1). Anything else (directories, source files, a third entry) makes it invalid. Every SDK’s
hivec build produces one; you rarely need to touch it, but these rules explain addresses and errors.
Module manifest
Section titled “Module manifest”{"compiler":"hivec-rs/0.2.0","functions":["addNumbers","increment"],"language":"rust","name":"my_module","runtime":"hive-wasm-v1"}| Key | Required | Rule |
|---|---|---|
name |
yes | 1–128 bytes |
language |
yes | [a-z0-9_+-]{1,32}, informational (rust, go, assemblyscript, javascript, python, …) |
compiler |
yes | 1–128 bytes, informational |
runtime |
yes | exactly "hive-wasm-v1" |
functions |
yes | 1–256 names [A-Za-z_][A-Za-z0-9_]{0,63}, sorted ascending by byte value, unique |
version |
no | ≤ 1024 bytes (--module-version) |
description |
no | ≤ 1024 bytes |
manifest_address |
no | if present, must equal the computed address |
No other keys (no timestamps, no consensus), no duplicate keys, no floats. The same build always yields the
same manifest.
Content address
Section titled “Content address”manifest_address = "0x" + hex(keccak256(canonical_json(manifest without manifest_address) ‖ module.wasm))Keccak-256 is Ethereum’s, not SHA3-256. The address is verified everywhere an artifact enters a trust boundary: the Hub on upload, a node on fetch and on every cache read. Archive bytes (compression, entry timestamps) are not part of the address.
Because the address covers the compiler string and the exact wasm, the same source compiled with a different SDK revision or toolchain version gives a different address. Pin your toolchain if you need reproducible addresses; the SDK examples rebuild to the exact addresses deployed on the testnet.
Function ids
Section titled “Function ids”A function’s func_id is its zero-based index in the sorted functions list. hivec functions and
ndsr inspect print them. Registration order in your source does not matter.
Size limits
Section titled “Size limits”.hbc |
16 MiB |
module.wasm |
12 MiB |
manifest.json |
64 KiB |
The guest ABI (for toolchain authors)
Section titled “The guest ABI (for toolchain authors)”| Export | Signature | Meaning |
|---|---|---|
memory |
32-bit, non-shared | linear memory |
__alloc |
(len: i32) -> i32 |
a pointer to len writable bytes in memory |
__hive_entry |
(func_id: i32, ptr: i32, len: i32) -> i64 |
run func_id on the input bytes; return (ptr << 32) | len of the output, or a negative value to fail |
The node allocates the input with __alloc, calls __hive_entry, and reads the output from the packed
return value. Host functions that return data (storage.get, hive.call, crypto.hash) use the same
packed convention. Allowed imports are listed in Host functions; any other
import, any WASI import, or the legacy __hive_entry_str ABI makes the module invalid. A module may not
export names starting with __ndsr_ (they are reserved for the injected stack limit).