Hyperledger Fabric Architecture Overview and Chaincode Development Guide

Architecture Design

The overall architecture is illustrated in the figure below.

The system consists of three major components: Blockchain Service, Chaincode Service, and Membership Management.

Basic Terminology

Transaction : Execution of a function call on the ledger, implemented in chaincode.

Transactor : Client that initiates a transaction.

Ledger : The blockchain containing all transaction records and the current world state.

World State : A stable snapshot of the ledger, represented by key‑value pairs, typically identified by {chaincodeID, ckey} .

Chaincode : Application code on the blockchain, an extension of “smart contracts”, supporting Go, Node.js, etc.

Validating Peer : Core node that maintains the ledger, participates in consensus, and validates/executed transactions.

Non‑validating Peer : Does not maintain the ledger; acts as a transaction proxy and forwards requests to validating peers.

Permissioned Ledger : All network nodes must be authorized; unauthorized nodes cannot join.

Privacy : The transactor’s identity can be hidden from other members without special permission.

Confidentiality : Only the transaction parties can view the transaction content.

Auditability : Transactions can be audited under appropriate permissions.

Blockchain Service

The blockchain service provides a distributed ledger platform where multiple transactions are packed into blocks, and blocks form a chain.

Transaction

A transaction operates around a specific chaincode and can modify the world state.

Key fields of a transaction include:

Transaction type (Deploy, Invoke, Query, Terminate)

UUID – unique identifier

Chaincode ID (chaincodeID)

Payload hash

Confidentiality level

Metadata

Nonce (security‑related)

Certificate (cert)

Signature

Timestamp

The protobuf definition of a transaction is:

message Transaction {
    enum Type {
        UNDEFINED = 0;
        // deploy a chaincode to the network and call `Init` function
        CHAINCODE_DEPLOY = 1;
        // call a chaincode `Invoke` function as a transaction
        CHAINCODE_INVOKE = 2;
        // call a chaincode `query` function
        CHAINCODE_QUERY = 3;
        // terminate a chaincode; not implemented yet
        CHAINCODE_TERMINATE = 4;
    }
    Type type = 1;
    bytes chaincodeID = 2;
    bytes payload = 3;
    bytes metadata = 4;
    string uuid = 5;
    google.protobuf.Timestamp timestamp = 6;
    ConfidentialityLevel confidentialityLevel = 7;
    string confidentialityProtocolVersion = 8;
    bytes nonce = 9;
    bytes toValidators = 10;
    bytes cert = 11;
    bytes signature = 12;
}

Block

Blocks package transactions and confirm the resulting world state.

Key fields of a block include:

Version number

Timestamp (set by the block proposer)

Merkle root of transaction hashes

Merkle root of the world state

Hash of the previous block

Consensus‑related metadata (optional)

Non‑hash data (e.g., local commit time, execution results)

Note: Detailed transaction data is not stored inside the block.

The protobuf definition of a block is:

message Block {
    uint32 version = 1;
    google.protobuf.Timestamp timestamp = 2;
    repeated Transaction transactions = 3;
    bytes stateHash = 4;
    bytes previousBlockHash = 5;
    bytes consensusMetadata = 6;
    NonHashData nonHashData = 7;
}

An example of a real block (JSON representation) is shown below:

{
    "nonHashData": {
        "localLedgerCommitTimestamp": {"nanos": 975295157, "seconds": 1466057539},
        "transactionResults": [{"uuid": "7be1529ee16969baf9f3156247a0ee8e7eee99a6a0a816776acff65e6e1def71249f4cb1cad5e0f0b60b25dd2a6975efb282741c0e1ecc53fa8c10a9aaa31137"}]
    },
    "previousBlockHash": "RrndKwuojRMjOz/rdD7rJD/NUupiuBuCtQwnZG7Vdi/XXcTd2MDyAMsFAZ1ntZL2/IIcSUeatIZAKS6ss7fEvg==",
    "stateHash": "TiIwROg48Z4xXFFIPEunNpavMxnvmZKg+yFxKK3VBY0zqiK3L0QQ5ILIV85iy7U+EiVhwEbkBb1Kb7w1ddqU5g==",
    "transactions": [{
        "chaincodeID": "CkdnaXRodWIuY29tL2h5cGVybGVkZ2VyL2ZhYnJpYy9leGFtcGxlcy9jaGFpbmNvZGUvZ28vY2hhaW5jb2RlX2V4YW1wbGUwMhKAATdiZTE1MjllZTE2OTY5YmFmOWYzMTU2MjQ3YTBlZThlN2VlZTk5YTZhMGE4MTY3NzZhY2ZmNjVlNmUxZGVmNzEyNDlmNGNiMWNhZDVlMGYwYjYwYjI1ZGQyYTY5NzVlZmIyODI3NDFjMGUxZWNjNTNmYThjMTBhOWFhYTMxMTM3",
        "payload": "Cu0BCAESzAEKR2dpdGh1Yi5jb20vaHlwZXJsZWRnZXIvZmFicmljL2V4YW1wbGVzL2NoYWluY29kZS9nby9jaGFpbmNvZGVfZXhhbXBsZTAyEoABN2JlMTUyOWVlMTY5NjliYWY5ZjMxNTYyNDdhMGVlOGU3ZWVlOTlhNmEwYTgxNjc3NmFjZmY2NWU2ZTFkZWY3MTI0OWY0Y2IxY2FkNWUwZjBiNjBiMjVkZDJhNjk3NWVmYjI4Mjc0MWMwZTFlY2M1M2ZhOGMxMGE5YWFhMzExMzcaGgoEaW5pdBIBYRIFMTAwMDASAWISBTIwMDAw",
        "timestamp": {"nanos": 298275779, "seconds": 1466057529},
        "type": 1,
        "uuid": "7be1529ee16969baf9f3156247a0ee8e7eee99a6a0a816776acff65e6e1def71249f4cb1cad5e0f0b60b25dd2a6975efb282741c0e1ecc53fa8c10a9aaa31137"
    }]
}

Chaincode Service

Chaincode contains all business logic and exposes interfaces; external clients invoke these interfaces to modify the world state.

Supported transaction types are Deploy, Invoke, and Query.

Deploy : The VP node creates a sandbox for the chaincode, registers it via a REGISTER message, and then invokes the Init function.

Invoke : The VP node sends a TRANSACTION message to the sandbox’s shim, which calls the chaincode’s Invoke function.

Query : The VP node sends a QUERY message to the shim, which calls the chaincode’s Query function.

Different chaincodes may call or query each other.

Membership Management

PKI‑based membership management restricts node and client capabilities.

Three certificate types are used:

Enrollment Certificate (ECert) : Issued to users or nodes that have registration credentials; typically long‑lived.

Transaction Certificate (TCert) : Issued to users for a specific transaction; short‑lived.

TLS Certificate (TLSCert) : Secures network access and prevents eavesdropping.

Message Types

All inter‑node communication is carried by messages defined by the following protobuf structure:

message Message {
    enum Type {
        UNDEFINED = 0;
        DISC_HELLO = 1;
        DISC_DISCONNECT = 2;
        DISC_GET_PEERS = 3;
        DISC_PEERS = 4;
        DISC_NEWMSG = 5;
        CHAIN_STATUS = 6;
        CHAIN_TRANSACTION = 7;
        CHAIN_GET_TRANSACTIONS = 8;
        CHAIN_QUERY = 9;
        SYNC_GET_BLOCKS = 11;
        SYNC_BLOCKS = 12;
        SYNC_BLOCK_ADDED = 13;
        SYNC_STATE_GET_SNAPSHOT = 14;
        SYNC_STATE_SNAPSHOT = 15;
        SYNC_STATE_GET_DELTAS = 16;
        SYNC_STATE_DELTAS = 17;
        RESPONSE = 20;
        CONSENSUS = 21;
    }
    Type type = 1;
    bytes payload = 2;
    google.protobuf.Timestamp timestamp = 3;
}

Messages are categorized into four groups: Discovery, Transaction, Synchronization, and Consensus.

Discovery

Includes DISC_HELLO, DISC_GET_PEERS, DISC_PEERS.

Transaction

Includes Deploy, Invoke, Query.

Synchronization

Includes SYNC_GET_BLOCKS / SYNC_BLOCKS, SYNC_STATE_GET_SNAPSHOT / SYNC_STATE_SNAPSHOT, SYNC_STATE_GET_DELTAS / SYNC_STATE_DELTAS.

Consensus

CONSENSUS messages.

New Architecture Design

The current VP node performs all functions (receiving transactions, validation, consensus, ledger maintenance), leading to tight coupling and limited scalability.

A proposed redesign decouples these responsibilities into distinct roles:

Submitting Peer : Verifies client signatures, runs transactions, constructs chaincode proposals, and forwards them to endorsers; after gathering enough endorsements, it sends the request to the consenter.

Endorser Peer : Validates and checks permissions of proposals from the submitting peer (simulates the transaction) and returns endorsements.

Consenter : Provides global ordering for transactions without touching the ledger; essentially a logical queue.

Committing Peer : Maintains the ledger and writes the results of consensus‑approved transactions; may be merged with other roles.

Chaincode

What is Chaincode

Chaincode is a program deployed on Hyperledger Fabric nodes that interacts with the distributed ledger; it is effectively a smart contract. It runs inside an isolated sandbox (Docker container) on a VP node and is invoked via gRPC.

Fabric supports chaincode written in Go, JavaScript, Java, and other languages.

Implementing the Chaincode Interface (Go Example)

The core functions are Init , Invoke , and Query . Each function receives a function name and arguments; the difference lies in when they are called.

Dependencies

fmt : Standard printing functions.

errors : Standard error handling.

github.com/hyperledger/fabric/core/chaincode/shim : Provides stub.PutState and stub.GetState for writing and reading key‑value pairs on the ledger.

Init() Function

Called once when the chaincode is first deployed to perform initialization tasks.

Invoke() Function

Executes business logic; the resulting transaction is recorded in a block on the ledger.

Query() Function

Retrieves state from the ledger without modifying it.

Main() Function

Registers the chaincode with the peer; invoked when the chaincode instance is deployed.

Interacting with Chaincode

Interaction methods include the CLI and REST APIs (examples are provided in the repository).