(c) 2026 Cyborg Unicorn Pty Ltd - MIT License
The ZOSCII Tamperproof Blockchain (ZTB) provides:
The reference implementation is a C# library (clsZTB / ZTBChain). The C command-line tools described in this guide are a binary-compatible implementation of the same on-disk format, intended for scripting, automation, and environments without a .NET runtime.
| Aspect | Traditional Blockchain | ZTB |
|---|---|---|
| Block Linking | Cryptographic hashes (SHA-256) | ZOSCII pointer encoding |
| Security Basis | Computational difficulty | Combinatorial impossibility |
| Quantum Threat | Vulnerable | Immune |
| Data Structure | Linear chain | Tree (trunk + branches) |
| Decoding Speed | Hash verification | O(1) pointer lookup |
Immutable root of trust. A file of exactly 65,536 bytes whose first byte is the block type marker (0 = Genesis); the remaining 65,535 bytes are high-entropy data containing all 256 byte values. Identified on disk purely by its size — there is no separate magic header.
⚠️ Lost Genesis Block = Unrecoverable Blockchain (unless a checkpoint + truncation has already established a self-contained root further up the chain — see Section 4, ztbtruncate)
Built from samples of previous blocks (up to 64 blocks × 1KB each, taken from the start of each block's complete serialized bytes — raw header plus ZOSCII-encoded section), with any remaining space filled from the genesis block (or, below a truncation marker, from the truncation block's stored ROM payload). Acts as the encoding/decoding table for one specific block. In the C# reference, block bytes are fetched through a pluggable callback — disk is only the default fallback when no callback is supplied; the same chain logic works equally over a database, an in-memory store, cloud blob storage, or a web service call, since clsZTB never assumes a specific transport. The C tools always read from disk directly, since no callback mechanism exists in C.
Each byte (1 byte) → pointer (2 bytes) into the Rolling ROM. Random selection among all matching addresses creates non-deterministic encoding — the same payload encodes differently every time it is written.
Genesis Block (64KB, byte[0]=0)
↓
Trunk Block 1
↓
Trunk Block 2
├─→ Branch A Block 1
│ ↓
│ Branch A Block 2
│
├─→ Branch B Block 1
│ ↓
│ Branch B Block 2
↓
Trunk Block 3
Every block carries a block_type byte in its raw header:
| Value | Name | Purpose |
|---|---|---|
| 0 | Genesis | The 64KB root-of-trust block |
| 1 | Normal | Standard data block (also used for branch blocks — see below) |
| 2 | Checkpoint | Documented anchor point, payload is a label string |
| 3 | Truncation | Written by Truncate(); payload is a raw 64KB rolling ROM snapshot |
| 4 | Finalise | Soft close marker; payload is a label string |
| 5 | Bridge | Reserved for future cross-chain linking |
A separate is_branch flag and trunk_id field in the raw header (not the block type) distinguish a branch block from a trunk block. Branch blocks are written with block_type = Normal — branching is orthogonal to block type.
The C# ZTBChain class (over the clsZTB engine) is the primary, canonical interface. All examples below use the same block IDs as the CLI examples further down, so the two can be compared directly.
ZTBChain objChain = ZTBChain.Open(strWorkDir, "MyTrunk");
// Optional third argument selects the hash algorithm; defaults to ZTBHashType.RollingFull
ZTBChain objChain2 = ZTBChain.Open(strWorkDir, "MyTrunk", ZTBHashType.CRC32Full);
strChainID here is, like the C tools' chain_id, a label for your own bookkeeping — it is not written into any block file. Note the default hash algorithm is RollingFull in C#, whereas the C tools always write CRC32Full — open with ZTBHashType.CRC32Full explicitly if blocks need to be readable by the C tools. (The C hashing primitive can compute CRC321KB if called with that value, but none of the C command-line tools currently expose a way to select it — they always request CRC32Full.)
A ZTBChain instance reads and writes blocks through three optional callback fields. When left null, the chain falls back to plain disk I/O against strWorkDir. Setting any of them redirects that operation to wherever you want — a database, an in-memory store, cloud blob storage, a web service call — with no change to the rest of the chain logic, since clsZTB never assumes a specific transport.
objChain.OnLoadBlock = (strFilename) =>
{
// Return the raw bytes for strFilename (e.g. ".ztb"), or null if not found
return myDatabase.ReadBlockBytes(strFilename);
};
objChain.OnSaveBlock = (objResult, arrBytes, strFilepath) =>
{
// Persist arrBytes however you like; return true on success
return myDatabase.WriteBlockBytes(strFilepath, arrBytes);
};
objChain.OnFindGenesis = (strUnused) =>
{
// Return the genesis block's bytes (the one 65,536-byte block), or null to fall back to disk
return myDatabase.ReadGenesisBytes();
};
All three are independent — you can override just OnLoadBlock for a read-only mirror, for instance, while leaving saves on disk. The C command-line tools have no equivalent: they always read and write the working directory directly, since C has no callback/delegate mechanism to plug in.
ZTBBlockResult objR1 = objChain.AddBlockText(
"3CEA0E03-1632-4531-A75B-78AE04C0522C", clsZTB.NULL_GUID, "Genesis block");
ZTBBlockResult objR2 = objChain.AddBlockText(
"9F1A2B3C-4D5E-4F60-8172-839405A6B7C8", objR1.BlockID, "Block 2");
ZTBBlockResult objR3 = objChain.AddBlockFile(
"1A2B3C4D-5E6F-4071-8293-A4B5C6D7E8F9", objR2.BlockID, "invoice.pdf");
if (!objR3.Success) { /* handle failure */ }
AddBlock takes a raw byte[] payload directly; AddBlockText and AddBlockFile are convenience wrappers around it.
// Branch off an existing trunk block
ZTBBlockResult objBranch = objChain.AddBranch(
"2B3C4D5E-6F70-4182-93A4-B5C6D7E8F9A0", objR2.BlockID,
Encoding.UTF8.GetBytes("Sales Genesis"), "CompanyLedger");
// Checkpoint, then truncate immediately, before adding further blocks above it
ZTBBlockResult objCP = objChain.AddCheckpoint(
"4D5E6F70-8192-4304-B5C6-D7E8F9A0B1C2", objR3.BlockID, "End of financial year");
ZTBBlockResult objTrunc = objChain.Truncate(Guid.NewGuid().ToString(), objCP.BlockID);
// Soft-close a chain
ZTBBlockResult objFin = objChain.Finalise(
"5E6F7081-92A3-4415-C6D7-E8F9A0B1C2D3", objCP.BlockID, "Chain closed");
ZTBBlockResult objFetched = objChain.FetchBlock("9F1A2B3C-4D5E-4F60-8172-839405A6B7C8");
if (objFetched.Success)
{
string strText = Encoding.UTF8.GetString(objFetched.Payload);
}
// blnWalk = true walks backwards through the whole chain; false checks only this block
ZTBVerifyResult objVerify = objChain.Verify("1A2B3C4D-5E6F-4071-8293-A4B5C6D7E8F9", true);
if (objVerify.Success)
{
Console.WriteLine(objVerify.VerifiedBlocks + " blocks verified, " +
objVerify.FailedBlocks + " failed");
}
The C command-line tools below are a binary-compatible implementation of the same on-disk format used by ZTBChain above — files written by one can be read by the other, provided the C# chain was opened with ZTBHashType.CRC32Full (the C tools' only implemented algorithm). They exist for scripting, automation, and environments without a .NET runtime.
All tools operate against a working directory containing one genesis block and any number of <blockID>.ztb files. There is no chain-ID-based filename scanning — every operation is addressed by explicit block ID (a GUID or any string you choose), matching the C# API's block-ID-based model exactly.
Creates the 64KB high-entropy genesis block file.
ztbcreate <source1> [source2] [source3] <workdir> <new_block_id>
Example:
ztbcreate selfie.jpg . A1B2C3D4-E5F6-4A7B-8C9D-E0F1A2B3C4D5
1–3 source files are XOR-blended byte-for-byte across the genesis block to produce the entropy. Recommended sources are JPEGs, MP3s, or any other capture of real-world physical data.
Adds a new normal block to an existing chain (trunk or branch).
ztbaddblock <workdir> <chain_id> <new_block_id> <prev_block_id> -t "text string"
ztbaddblock <workdir> <chain_id> <new_block_id> <prev_block_id> -f <file_path>
chain_id is a free-text label for your own bookkeeping — it is not written into the file or used for lookups. prev_block_id is the GUID of the block this one links to; use 00000000-0000-0000-0000-000000000000 for the first block in a chain.
Examples:
# First block of a new trunk
ztbaddblock . MyTrunk 3CEA0E03-1632-4531-A75B-78AE04C0522C 00000000-0000-0000-0000-000000000000 -t "Genesis block"
# Add a second block, linked to the first
ztbaddblock . MyTrunk 9F1A2B3C-4D5E-4F60-8172-839405A6B7C8 3CEA0E03-1632-4531-A75B-78AE04C0522C -t "Block 2"
# Add a file as payload
ztbaddblock . MyTrunk 1A2B3C4D-5E6F-4071-8293-A4B5C6D7E8F9 9F1A2B3C-4D5E-4F60-8172-839405A6B7C8 -f invoice.pdf
Options:
-t "text" - Add a UTF-8 text string as payload-f filename - Add a file's contents as payloadWrites a block with is_branch = 1 and a trunk_id reference, splitting a new branch chain off from any existing block (typically a trunk block).
ztbaddbranch <workdir> <trunk_chain_id> <branch_chain_id> <new_block_id> <prev_block_id> -t "text"
ztbaddbranch <workdir> <trunk_chain_id> <branch_chain_id> <new_block_id> <prev_block_id> -f <file>
Example:
# Trunk block already exists at prev_block_id
ztbaddbranch . CompanyLedger Sales 2B3C4D5E-6F70-4182-93A4-B5C6D7E8F9A0 9F1A2B3C-4D5E-4F60-8172-839405A6B7C8 -t "Sales Genesis"
# Further blocks on the branch use the normal ztbaddblock tool
ztbaddblock . Sales 3C4D5E6F-7081-4293-A4B5-C6D7E8F9A0B1 2B3C4D5E-6F70-4182-93A4-B5C6D7E8F9A0 -t "Sale #001"
Adds a documented anchor point to a chain. Identical in every respect to ztbaddblock except the block type is Checkpoint and the payload is always a plain label string.
ztbcheckpoint <workdir> <chain_id> <new_block_id> <prev_block_id> <label>
Example:
ztbcheckpoint . FY2025 4D5E6F70-8192-4304-B5C6-D7E8F9A0B1C2 3C4D5E6F-7081-4293-A4B5-C6D7E8F9A0B1 "End of financial year"
Severs a chain at a checkpoint for archival. Reads the checkpoint's prev_block_id (call this block10), builds the rolling ROM exactly as block10's successor would have built it, then overwrites block10's own file with a Truncation block whose payload is that raw 64KB ROM snapshot — unencoded, since nothing below it remains to reference.
ztbtruncate <workdir> <checkpoint_block_id>
Example:
ztbtruncate . 4D5E6F70-8192-4304-B5C6-D7E8F9A0B1C2
After truncation, all blocks below block10 (the original genesis included) can be moved to cold storage. The active chain remains fully self-contained and independently verifiable using only the files from the checkpoint upward.
Retrieves and decodes a specific block by ID, verifying its integrity.
ztbfetch <workdir> <block_id>
Example:
ztbfetch . 9F1A2B3C-4D5E-4F60-8172-839405A6B7C8
Verifies a single block, or walks backwards from a given block to the start of the chain (or to a truncation marker, whichever comes first), checking the integrity hash and previous-block hash binding at every step.
# Verify a single block only
ztbverify <workdir> <block_id>
# Walk backwards verifying the whole chain
ztbverify <workdir> <block_id> -walk
Example:
ztbverify . 1A2B3C4D-5E6F-4071-8293-A4B5C6D7E8F9 -walk
0 (Genesis)<block_id>.ztb
There is no chain ID or index number in the filename. A block's chain membership and position are entirely determined by the trunk_id and prev_block_id fields inside its own raw header — the filename is just the block's own ID.
Examples:
A0B9845E-1234-4567-89AB-CDEF01234567.ztb ← genesis block (identified by 65536-byte size)
3CEA0E03-1632-4531-A75B-78AE04C0522C.ztb ← any other block
Every non-genesis .ztb file is structured as:
[ 111 bytes: raw, unencoded header ][ N bytes: ZOSCII-encoded section ]
Exception — Truncation blocks: the 111-byte raw header is followed by a raw, unencoded 65,536-byte rolling ROM snapshot, since there is no prior block left to ZOSCII-encode against.
| Offset | Size | Field | Description |
|---|---|---|---|
| 0 | 1 | block_type | Genesis=0, Normal=1, Checkpoint=2, Truncation=3, Finalise=4, Bridge=5 |
| 1 | 1 | block_version | Format version (currently 1) |
| 2 | 1 | is_branch | 1 if this block belongs to a branch chain, else 0 |
| 3–38 | 36 | trunk_id | Trunk chain ID (ASCII, zero-padded); NULL_GUID for trunk blocks |
| 39–74 | 36 | block_id | This block's own ID (ASCII, zero-padded) |
| 75–110 | 36 | prev_block_id | Previous block's ID (ASCII, zero-padded); NULL_GUID for the first block of a chain |
| Offset (decoded) | Size | Field | Description |
|---|---|---|---|
| 0 | 1 | hash_type | CRC32Full=0, CRC321KB=1, RollingFull=2, Rolling1KB=3 |
| 1–4 | 4 | hash | Hash of the padded payload only — not the header, not the link/length metadata. Computed before ZOSCII encoding is applied, little-endian |
| 5–8 | 4 | prev_hash | Hash of the previous block's complete serialized bytes, same algorithm; zero for the first block of a chain, little-endian |
| 9–12 | 4 | payload_len | Actual payload length in bytes, little-endian |
| 13–16 | 4 | padded_len | Padded payload length (minimum 440 bytes, the smallest value that guarantees the complete on-disk block reaches at least 1024 bytes — see Rolling ROM Construction), little-endian |
| 17+ | padded_len | payload | The payload, padded with random bytes (when needed to reach the minimum) up to padded_len |
The encoded section is ZOSCII-encoded as a single unit using the rolling ROM, expanding each raw byte to 2 bytes on disk.
Hash algorithm note: the C command-line tools implement CRC32Full only; RollingFull and Rolling1KB are present as stubs (return 0) for forward compatibility with the C# reference, which implements the ZRollingHash algorithm in full.
prev_block_id via each block's own prev_block_id, collecting up to 64 blocks (stopping early if a Truncation block is reached).ztb file in the working directory whose size is exactly 65,536 bytes)The 1KB sample is taken from each block's complete serialized form — raw header followed by ZOSCII-encoded section — not from the decoded payload. This is a reconstruction requirement, not a security one: the rolling ROM is not secret and provides no protection by being statistically random, since every verifier rebuilds it exactly the same way by walking the chain. The reason the encoded bytes are sampled is simpler — they are the bytes actually stored in the block, byte-for-byte identical for anyone reconstructing the chain. Sampling the decoded payload instead would require re-deriving it (decoding requires the very rolling ROM being built, making it circular), and would also expose the same 1KB of plaintext payload across every dependent block's ROM, which the encoded form avoids.
If an attacker modifies Block N:
This is combinatorially infeasible - not just hard, but information-theoretically impossible.
Every block commits to two hash values in its encoded section:
CRC321KB/Rolling1KB the hash is further clamped to the first 1024 bytes of the padded payload.CRC321KB/Rolling1KB, the first 1024 bytes of them. This one covers everything, header included, because by the time it's hashed the previous block is already a finished, fully-committed artifact with no streaming concern — unlike the current block's payload, which may not be.This dual-hash binding is always active — it is a standard feature of every block, not an optional mode. The first block of a chain has no predecessor; its prev-hash field is zero by design.
Because the current-block hash is payload-only, it does not by itself protect the header fields (prev_block_id, trunk_id, is_branch, block_id) from tampering. That protection instead comes from the rolling ROM: the header is part of each block's on-disk bytes, and the first 1KB of those bytes — header included — gets sampled into every dependent block's rolling ROM, making header tampering subject to the same combinatorial tamper-evidence as the payload, rather than the hash.
1KB threshold: the rolling ROM samples the first 1KB of each block's complete serialized bytes (header + encoded section). The current-block hash, by contrast, only ever covers the padded payload — under CRC32Full/RollingFull all of it, under CRC321KB/Rolling1KB just the first 1024 bytes of it. These two 1KB windows are related but not identical: the rolling-ROM sample's 1KB includes the 111-byte header, while the hash's 1KB (under the windowed variants) is 1024 bytes of payload with no header mixed in.
| Attack Vector | Traditional Blockchain | ZTB |
|---|---|---|
| Shor's Algorithm | Breaks PKI | No PKI to break |
| Grover's Algorithm | Weakens hashing | Hashing is a secondary check, not the primary tamper-evidence mechanism |
| Brute Force | 2^256 operations | 10^152900 permutations |
| Quantum Computer | Eventually vulnerable | Immune |
# Windows (Visual Studio Developer Command Prompt)
cl /O2 /MT ztbcreate.c /link
cl /O2 /MT ztbaddblock.c /link
cl /O2 /MT ztbaddbranch.c /link
cl /O2 /MT ztbcheckpoint.c /link
cl /O2 /MT ztbtruncate.c /link
cl /O2 /MT ztbfetch.c /link
cl /O2 /MT ztbverify.c /link
# Linux / macOS (gcc)
gcc -O2 -o ztbcreate ztbcreate.c
gcc -O2 -o ztbaddblock ztbaddblock.c
gcc -O2 -o ztbaddbranch ztbaddbranch.c
gcc -O2 -o ztbcheckpoint ztbcheckpoint.c
gcc -O2 -o ztbtruncate ztbtruncate.c
gcc -O2 -o ztbfetch ztbfetch.c
gcc -O2 -o ztbverify ztbverify.c
Each tool is a single self-contained .c file that includes ztbcommon.c directly — no separate linking step is needed for the shared code, and no external libraries are required.
ZTBChain objChain = ZTBChain.Open(strWorkDir, "MyTrunk", ZTBHashType.CRC32Full);
ZTBBlockResult objB1 = objChain.AddBlockText(
"A0000001-0000-4000-8000-000000000002", clsZTB.NULL_GUID, "Block 1");
ZTBBlockResult objB2 = objChain.AddBlockText(
"A0000001-0000-4000-8000-000000000003", objB1.BlockID, "Block 2");
ZTBBlockResult objB3 = objChain.AddBlockText(
"A0000001-0000-4000-8000-000000000004", objB2.BlockID, "Block 3");
ZTBVerifyResult objV = objChain.Verify(objB3.BlockID, true);
ZTBBlockResult objFetched = objChain.FetchBlock(objB2.BlockID);
# 1. Create the genesis block
ztbcreate selfie.jpg . A0000001-0000-4000-8000-000000000001
# 2. Create a trunk chain (each block's prev_block_id links to the one before)
ztbaddblock . MyTrunk A0000001-0000-4000-8000-000000000002 00000000-0000-0000-0000-000000000000 -t "Block 1"
ztbaddblock . MyTrunk A0000001-0000-4000-8000-000000000003 A0000001-0000-4000-8000-000000000002 -t "Block 2"
ztbaddblock . MyTrunk A0000001-0000-4000-8000-000000000004 A0000001-0000-4000-8000-000000000003 -t "Block 3"
# 3. Verify the whole chain
ztbverify . A0000001-0000-4000-8000-000000000004 -walk
# 4. Fetch a specific block
ztbfetch . A0000001-0000-4000-8000-000000000003
# 1. Create genesis
ztbcreate selfie.jpg . B0000001-0000-4000-8000-000000000001
# 2. Create company trunk
ztbaddblock . CompanyLedger B0000001-0000-4000-8000-000000000002 00000000-0000-0000-0000-000000000000 -t "FY2025 Genesis"
# 3. Branch for departments (each anchored to the trunk block above)
ztbaddbranch . CompanyLedger Sales B0000001-0000-4000-8000-000000000003 B0000001-0000-4000-8000-000000000002 -t "Sales Dept"
ztbaddbranch . CompanyLedger Marketing B0000001-0000-4000-8000-000000000004 B0000001-0000-4000-8000-000000000002 -t "Marketing Dept"
# 4. Add department records (chained off the branch's own first block)
ztbaddblock . Sales B0000001-0000-4000-8000-000000000005 B0000001-0000-4000-8000-000000000003 -f invoice_001.pdf
# 5. Verify the branch back through the trunk
ztbverify . B0000001-0000-4000-8000-000000000005 -walk
# Build a chain, then checkpoint and truncate it
ztbaddblock . FYChain C0000001-...0002 00000000-...-000000000000 -t "Block 1"
ztbaddblock . FYChain C0000001-...0003 C0000001-...0002 -t "Block 2"
ztbcheckpoint . FYChain C0000001-...0004 C0000001-...0003 "End of FY2025"
# Truncate FIRST, before adding any block above the checkpoint
ztbtruncate . C0000001-...0004
# Now continue the chain — new blocks build on the truncated history correctly
ztbaddblock . FYChain C0000001-...0005 C0000001-...0004 -t "First FY2026 block"
ztbverify ... -walk