Skip to content

Data models

Internal event schema

EVENT_SCHEMA in hierachain/core/block.py defines the Arrow representation:

from hierachain.core.block import EVENT_SCHEMA

print(EVENT_SCHEMA)
Field Arrow type
entity_id string
event string
timestamp double
details map<string, string>
details_cid string
details_nonce string
data binary

The data column stores canonical JSON event bytes generated by block conversion. Arrow detail values are strings, while Block.to_event_list() recovers JSON types and nested details from those bytes. Additional JSON fields are preserved in the payload even if they have no dedicated Arrow column. Top-level fields containing bytes or bytearray are omitted by serialize_event_payload(); nested values must be JSON-serializable. data is an internal payload column, not a REST file-upload field.

REST and SDK input

EventRequest in hierachain/api/ledger/schemas.py uses event_type; the server constructs an internal event with event and a server timestamp. entity_id and event_type are required. Optional fields are details, details_cid, details_nonce, details_metadata, sender and signature.

from hierachain.api.ledger.schemas import EventRequest

request = EventRequest(
    entity_id="PROD-001",
    event_type="production_complete",
    details={"quantity": 100, "passed": True},
)
print(request.model_dump(exclude_none=True))

Details are limited to approximately 1 MiB of serialized JSON and nesting depth 10. A supplied nonce must be 24 hexadecimal characters (12 bytes). Use the nonce and authenticated metadata returned by encrypted IPFS upload; a sample CID/nonce is not a decryptable fixture. Cryptographic fields are validated when provided.

The proof endpoint uses the chain name in the URL and returns ProofSubmissionResponse. There is no ProofSubmissionRequest class in the ledger schema module.

Block representation

Block is a Python class with an Arrow events table. to_dict() emits index, events, timestamp, previous_hash, nonce, merkle_root, hash, creator_id and signature. There is no separate BLOCK_HEADER_SCHEMA or event table for another operation type.

This construction example demonstrates payload conversion only:

import time
from hierachain.core.block import Block

block = Block(
    index=1,
    previous_hash="previous-block-hash",
    events=[{
        "entity_id": "PROD-001",
        "event": "production_complete",
        "timestamp": time.time(),
        "details": {"quantity": 100},
    }],
)
assert block.to_event_list()[0]["details"]["quantity"] == 100

A constructed block is not yet an accepted ledger block. The base Blockchain.add_block() requires trusted signatures, valid linkage and Merkle/hash integrity; MainChain/SubChain add their consensus checks. Genesis also needs a trusted signature.

Block.from_dict() reconstructs data and compares a supplied string hash with the recalculated header hash. It accepts a supplied merkle_root without recomputing it, so changed event bytes can pass this header-only check. Use BlockVerifier with a trusted public key, or the chain's validation methods, to check event integrity and signatures. Block.validate_structure() checks that the event table contains entity_id, event and timestamp; it does not validate every Arrow type or event value.