What is hlf-core
Hyperledger Fabric offers a powerful but deliberately low-level model: a contract (chaincode)
sees state as a flat key-value store, authenticates the organization rather than the user, and
imposes neither a way to store entities nor a way to invoke operations. All of that you have to
build yourself — and, as a rule, from scratch on every project. hlf-core is the layer we built
once and factored out into the @hlf-core/* package set, so we never have to write it again.
In other words, it is a TypeScript framework for developing Fabric chaincode and client applications. It grew out of real production systems — financial accounting, a depository, custody — and gathers what those systems turned out to have in common: working with state, a command invocation protocol, user identification, and a token system.
What it takes care of
First of all, state. Instead of manual getState/putState calls, hlf-core provides an
ORM-like layer: entities, parent-child relationships, pagination, and automatic validation.
Keys are built so that a secondary lookup by the left-hand part of a composite key stays
predictable rather than degrading into a random range scan.
Next, operation invocation. In an ordinary contract each operation is a separate function, and
adding a new one changes its interface. We took a different route: the contract has a single
entry point, and any operation is wrapped in a command envelope whose name field determines
exactly what was invoked. On top of that comes end-user identification layered over Fabric's
organizational identity — an application-level signature and protection against transaction
replay via a nonce.
Finally, tokens. Emission, transfers, holds, burning, a full audit trail, and string-based arithmetic without loss of precision — all of it is already written and tested, not reinvented for every project. The same goes for parsing blocks and events: turning Fabric's raw data into a typed form you can actually work with.
What it is made of
hlf-core is a monorepo of published npm packages @hlf-core/*, arranged in layers: from a
platform-neutral foundation to a domain-specific pair of token packages.
| Layer | Packages | Purpose |
|---|---|---|
| Foundation | @hlf-core/common | Platform-neutral classes — state keys, identity, commands |
| Network / ORM | @hlf-core/api, @hlf-core/chaincode | Connecting to Fabric and an ORM over key-value |
| Transport | @hlf-core/transport, @hlf-core/transport-common, @hlf-core/transport-chaincode | The "client ↔ chaincode" protocol |
| Tokens | @hlf-core/coin, @hlf-core/coin-chaincode | Managing currencies and tokens |
Why there are exactly this many layers, and how a typical command travels through them, is covered in the Philosophy section; it also includes a diagram and a walkthrough of the path from client to block and back.
Where to start
If you have not worked with hlf-core before, the easiest way in is the Getting Started guide, building a minimal chaincode. If you would rather grasp the idea as a whole before writing any code, read the Philosophy. And if you are looking for a specific package, go straight to the Packages section.