Fabric Chaincode Tutorial: Go vs JS vs Java

Chaincode is where business logic meets the blockchain. Every asset transfer, every access control check, every compliance rule in a Hyperledger Fabric network runs as chaincode. According to the Hyperledger Foundation's 2024 survey, Go accounts for approximately 68% of production chaincode deployments, followed by JavaScript/Node.js at 22% and Java at 10%. But those numbers don't tell the whole story — the right language depends on your team, your performance requirements, and how fast you need to iterate.

I've written chaincode in all three languages across different projects. Go is my default for anything heading to production. JavaScript is what I reach for during rapid prototyping or when working with frontend-heavy teams. Java works well in large enterprise environments where the entire stack is already JVM-based. This tutorial gives you complete, working examples in all three so you can make your own informed choice.

TL;DR: Go is the best default for Fabric chaincode — it delivers the highest throughput (3,500+ TPS in optimized Fabric networks per the Hyperledger Performance Whitepaper, 2024), produces small binaries, and matches Fabric's own codebase. JavaScript/TypeScript wins for rapid prototyping and web-developer teams. Java fits enterprises already invested in JVM infrastructure.

If you already have a Fabric network running, you can skip ahead to the Go tutorial section. If you need a network first, follow our guide to create a Hyperledger Fabric network.

What Is Chaincode and How Does It Differ from Smart Contracts?

Chaincode is Fabric's term for smart contracts — programs that execute against the shared ledger to read and write state. The Hyperledger Fabric documentation defines chaincode as the business logic that governs how applications interact with the ledger. The key distinction from Ethereum smart contracts is that Fabric chaincode runs in a separate container (or process) rather than inside a virtual machine.

Chaincode vs. Ethereum Smart Contracts

On Ethereum (and Besu), smart contracts are compiled to bytecode and executed inside the EVM. Every validator runs the same bytecode deterministically. On Fabric, chaincode runs in its own Docker container or external process. The peer communicates with it over gRPC.

This architectural difference has practical consequences. Chaincode can use standard language features — file system access, external libraries, network calls (with caveats) — that EVM smart contracts can't. But it also means chaincode must be installed on every endorsing peer separately, and the lifecycle is more complex.

The Chaincode Lifecycle

Fabric's chaincode lifecycle has four phases: package, install, approve, and commit. This multi-step process provides governance guardrails that Ethereum deployments lack.

1. Package — Bundle the chaincode source into a tar.gz archive with metadata
2. Install — Upload the package to each endorsing peer
3. Approve — Each organization reviews and approves the chaincode definition
4. Commit — Once enough organizations approve (per the lifecycle endorsement policy), the chaincode is committed to the channel

This process ensures no single organization can deploy code that affects the shared ledger without multi-party agreement. It's bureaucratic, yes. But for regulated industries, that governance is a feature.

Fabric chaincode runs in isolated containers communicating over gRPC, unlike EVM smart contracts that execute inside a virtual machine. The four-phase lifecycle (package, install, approve, commit) enforces multi-organization governance over code deployments, as specified in the Hyperledger Fabric documentation.

Which Language Should You Choose for Chaincode?

Go dominates production deployments at 68% market share (Hyperledger Foundation, 2024), but language choice should follow team capabilities and project constraints. Here's a detailed comparison across the dimensions that actually matter in enterprise projects.

When to Choose Go

Pick Go when throughput matters, when you want the smallest attack surface (single binary, no runtime dependencies), or when your team already knows Go. Go chaincode matches Fabric's own language, which means debugging deep into Fabric internals is straightforward. The fabric-contract-api-go library is maintained by the Hyperledger community and stays current with Fabric releases.

When to Choose JavaScript or TypeScript

Pick JavaScript when your team is web-focused and you need fast iteration cycles. The npm ecosystem gives you access to thousands of utility libraries. TypeScript adds compile-time type checking that catches bugs before deployment. For proof-of-concept work, JavaScript's lower ceremony (no compilation step for plain JS) accelerates the feedback loop.

When to Choose Java

Pick Java when your organization standardizes on the JVM. Enterprise Java teams bring existing expertise in Maven/Gradle build systems, JUnit testing, and Spring-based dependency injection patterns. Java chaincode integrates naturally with enterprise middleware. The downside is JVM cold-start time and memory footprint.

How Do You Write a Complete Go Chaincode?

Here's a production-ready CRUD chaincode in Go that manages a generic asset. The fabric-contract-api-go library (v1.2+) provides the contract interface. This example includes input validation, error handling, and JSON serialization — patterns you'll reuse in every Go chaincode you write.

Project Setup

mkdir asset-chaincode && cd asset-chaincode
go mod init github.com/your-org/asset-chaincode
go get github.com/hyperledger/fabric-contract-api-go@v1.2.2

Your directory structure:

asset-chaincode/
  go.mod
  go.sum
  main.go
  chaincode/
    smartcontract.go
    asset.go

The Asset Model

// chaincode/asset.go
package chaincode
 
// Asset represents a generic ledger asset.
type Asset struct {
    ID        string `json:"id"`
    Owner     string `json:"owner"`
    Value     int    `json:"value"`
    Status    string `json:"status"`
    CreatedAt string `json:"createdAt"`
    UpdatedAt string `json:"updatedAt"`
}

The Smart Contract

// chaincode/smartcontract.go
package chaincode
 
import (
    "encoding/json"
    "fmt"
    "time"
 
    "github.com/hyperledger/fabric-contract-api-go/contractapi"
)
 
// SmartContract provides the chaincode functions.
type SmartContract struct {
    contractapi.Contract
}
 
// CreateAsset creates a new asset on the ledger.
func (s *SmartContract) CreateAsset(
    ctx contractapi.TransactionContextInterface,
    id string, owner string, value int,
) error {
    // Check if asset already exists
    existing, err := ctx.GetStub().GetState(id)
    if err != nil {
        return fmt.Errorf("failed to read ledger: %v", err)
    }
    if existing != nil {
        return fmt.Errorf("asset %s already exists", id)
    }
 
    now := time.Now().UTC().Format(time.RFC3339)
    asset := Asset{
        ID:        id,
        Owner:     owner,
        Value:     value,
        Status:    "active",
        CreatedAt: now,
        UpdatedAt: now,
    }
 
    assetJSON, err := json.Marshal(asset)
    if err != nil {
        return fmt.Errorf("failed to marshal asset: %v", err)
    }
 
    return ctx.GetStub().PutState(id, assetJSON)
}
 
// ReadAsset returns the asset stored in the ledger with the given ID.
func (s *SmartContract) ReadAsset(
    ctx contractapi.TransactionContextInterface,
    id string,
) (*Asset, error) {
    assetJSON, err := ctx.GetStub().GetState(id)
    if err != nil {
        return nil, fmt.Errorf("failed to read ledger: %v", err)
    }
    if assetJSON == nil {
        return nil, fmt.Errorf("asset %s does not exist", id)
    }
 
    var asset Asset
    err = json.Unmarshal(assetJSON, &asset)
    if err != nil {
        return nil, fmt.Errorf("failed to unmarshal asset: %v", err)
    }
 
    return &asset, nil
}
 
// UpdateAsset updates an existing asset's owner and value.
func (s *SmartContract) UpdateAsset(
    ctx contractapi.TransactionContextInterface,
    id string, newOwner string, newValue int,
) error {
    asset, err := s.ReadAsset(ctx, id)
    if err != nil {
        return err
    }
 
    asset.Owner = newOwner
    asset.Value = newValue
    asset.UpdatedAt = time.Now().UTC().Format(time.RFC3339)
 
    assetJSON, err := json.Marshal(asset)
    if err != nil {
        return fmt.Errorf("failed to marshal asset: %v", err)
    }
 
    return ctx.GetStub().PutState(id, assetJSON)
}
 
// DeleteAsset removes an asset from the ledger.
func (s *SmartContract) DeleteAsset(
    ctx contractapi.TransactionContextInterface,
    id string,
) error {
    existing, err := ctx.GetStub().GetState(id)
    if err != nil {
        return fmt.Errorf("failed to read ledger: %v", err)
    }
    if existing == nil {
        return fmt.Errorf("asset %s does not exist", id)
    }
 
    return ctx.GetStub().DelState(id)
}
 
// GetAllAssets returns all assets in the ledger.
func (s *SmartContract) GetAllAssets(
    ctx contractapi.TransactionContextInterface,
) ([]*Asset, error) {
    resultsIterator, err := ctx.GetStub().GetStateByRange("", "")
    if err != nil {
        return nil, fmt.Errorf("failed to get state range: %v", err)
    }
    defer resultsIterator.Close()
 
    var assets []*Asset
    for resultsIterator.HasNext() {
        queryResponse, err := resultsIterator.Next()
        if err != nil {
            return nil, err
        }
 
        var asset Asset
        err = json.Unmarshal(queryResponse.Value, &asset)
        if err != nil {
            return nil, err
        }
        assets = append(assets, &asset)
    }
 
    return assets, nil
}
 
// TransferAsset transfers an asset to a new owner.
func (s *SmartContract) TransferAsset(
    ctx contractapi.TransactionContextInterface,
    id string, newOwner string,
) error {
    asset, err := s.ReadAsset(ctx, id)
    if err != nil {
        return err
    }
 
    asset.Owner = newOwner
    asset.UpdatedAt = time.Now().UTC().Format(time.RFC3339)
 
    assetJSON, err := json.Marshal(asset)
    if err != nil {
        return fmt.Errorf("failed to marshal asset: %v", err)
    }
 
    return ctx.GetStub().PutState(id, assetJSON)
}

The Main Entry Point

// main.go
package main
 
import (
    "log"
 
    "github.com/hyperledger/fabric-contract-api-go/contractapi"
    "github.com/your-org/asset-chaincode/chaincode"
)
 
func main() {
    assetChaincode, err := contractapi.NewChaincode(&chaincode.SmartContract{})
    if err != nil {
        log.Panicf("Error creating chaincode: %v", err)
    }
 
    if err := assetChaincode.Start(); err != nil {
        log.Panicf("Error starting chaincode: %v", err)
    }
}

Advanced Go Patterns

Composite Keys let you create compound indexes for efficient range queries:

// Create a composite key for owner-based lookups
key, err := ctx.GetStub().CreateCompositeKey("owner~id", []string{asset.Owner, asset.ID})
if err != nil {
    return fmt.Errorf("failed to create composite key: %v", err)
}
ctx.GetStub().PutState(key, []byte{0x00})

Rich Queries (CouchDB only) enable JSON-based queries:

queryString := `{"selector":{"owner":"alice","status":"active"}}`
resultsIterator, err := ctx.GetStub().GetQueryResult(queryString)

Rich queries are powerful but carry a caveat: they're only available when the peer uses CouchDB as its state database, and they aren't suitable for endorsement-critical operations because CouchDB query results can vary between peers.

Go chaincode accounts for 68% of production Fabric deployments, delivering the highest throughput as native binaries with sub-second cold starts. The fabric-contract-api-go library provides the contract interface, with GetStub() methods for all state operations — PutState, GetState, DelState, and range/composite key queries (Hyperledger Foundation, 2024).

For AI-assisted chaincode generation that produces code in this exact pattern, see our guide on building chaincodes with AI.

Ready to deploy your own Fabric network? Book a call with David to discuss your use case, or start deploying now with ChainLaunch.

How Do You Write Chaincode in JavaScript?

The JavaScript/TypeScript contract API mirrors the Go API in structure. The fabric-contract-api npm package (part of the fabric-shim family) handles the gRPC communication with the peer. According to npm download statistics, the package averages over 4,000 weekly downloads in 2026 — a healthy and active ecosystem.

Project Setup

mkdir asset-chaincode-js && cd asset-chaincode-js
npm init -y
npm install fabric-contract-api fabric-shim

The Contract

'use strict';
 
const { Contract } = require('fabric-contract-api');
 
class AssetContract extends Contract {
 
    async CreateAsset(ctx, id, owner, value) {
        const existing = await ctx.stub.getState(id);
        if (existing && existing.length > 0) {
            throw new Error(`Asset ${id} already exists`);
        }
 
        const now = new Date().toISOString();
        const asset = {
            id,
            owner,
            value: parseInt(value, 10),
            status: 'active',
            createdAt: now,
            updatedAt: now,
        };
 
        await ctx.stub.putState(id, Buffer.from(JSON.stringify(asset)));
        return JSON.stringify(asset);
    }
 
    async ReadAsset(ctx, id) {
        const assetJSON = await ctx.stub.getState(id);
        if (!assetJSON || assetJSON.length === 0) {
            throw new Error(`Asset ${id} does not exist`);
        }
        return assetJSON.toString();
    }
 
    async UpdateAsset(ctx, id, newOwner, newValue) {
        const assetString = await this.ReadAsset(ctx, id);
        const asset = JSON.parse(assetString);
 
        asset.owner = newOwner;
        asset.value = parseInt(newValue, 10);
        asset.updatedAt = new Date().toISOString();
 
        await ctx.stub.putState(id, Buffer.from(JSON.stringify(asset)));
        return JSON.stringify(asset);
    }
 
    async DeleteAsset(ctx, id) {
        const existing = await ctx.stub.getState(id);
        if (!existing || existing.length === 0) {
            throw new Error(`Asset ${id} does not exist`);
        }
        await ctx.stub.deleteState(id);
    }
 
    async GetAllAssets(ctx) {
        const results = [];
        const iterator = await ctx.stub.getStateByRange('', '');
 
        let result = await iterator.next();
        while (!result.done) {
            const strValue = Buffer.from(
                result.value.value.buffer
            ).toString('utf8');
            results.push(JSON.parse(strValue));
            result = await iterator.next();
        }
 
        return JSON.stringify(results);
    }
 
    async TransferAsset(ctx, id, newOwner) {
        const assetString = await this.ReadAsset(ctx, id);
        const asset = JSON.parse(assetString);
 
        asset.owner = newOwner;
        asset.updatedAt = new Date().toISOString();
 
        await ctx.stub.putState(id, Buffer.from(JSON.stringify(asset)));
        return JSON.stringify(asset);
    }
}
 
module.exports = AssetContract;

TypeScript Considerations

For TypeScript, add type annotations and use the decorator-based API for cleaner contract definitions. Install the additional dependencies:

npm install typescript @types/node
npm install fabric-contract-api fabric-shim

The key TypeScript advantages: compile-time type checking catches parameter mismatches before deployment, and interfaces make the data model explicit. The trade-off is an additional compilation step and slightly more verbose code.

In my experience, TypeScript is worth the overhead for any chaincode that will be maintained by a team larger than two people. The type annotations serve as documentation that the compiler enforces.

How Do You Write Chaincode in Java?

Java chaincode uses the fabric-chaincode-java library with annotation-based contract definitions. According to Maven Central statistics, the fabric-chaincode-shim artifact sees approximately 1,200 monthly downloads — smaller than the JavaScript ecosystem but stable among enterprise Java shops.

Project Setup (Gradle)

// build.gradle
plugins {
    id 'java'
    id 'com.github.johnrengelman.shadow' version '8.1.1'
}
 
group = 'com.example'
version = '1.0.0'
 
dependencies {
    implementation 'org.hyperledger.fabric-chaincode-java:fabric-chaincode-shim:2.5.3'
    implementation 'com.google.code.gson:gson:2.10.1'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'
    testImplementation 'org.mockito:mockito-core:5.10.0'
}

The Contract

package com.example.chaincode;
 
import org.hyperledger.fabric.contract.ContractInterface;
import org.hyperledger.fabric.contract.Context;
import org.hyperledger.fabric.contract.annotation.*;
import org.hyperledger.fabric.shim.ChaincodeException;
import com.google.gson.Gson;
import java.time.Instant;
 
@Contract(name = "AssetContract")
@Default
public class AssetContract implements ContractInterface {
 
    private final Gson gson = new Gson();
 
    @Transaction(intent = Transaction.TYPE.SUBMIT)
    public String CreateAsset(Context ctx, String id,
                              String owner, int value) {
        byte[] existing = ctx.getStub().getState(id);
        if (existing != null && existing.length > 0) {
            throw new ChaincodeException(
                "Asset " + id + " already exists"
            );
        }
 
        String now = Instant.now().toString();
        Asset asset = new Asset(id, owner, value,
                                "active", now, now);
        String json = gson.toJson(asset);
        ctx.getStub().putStringState(id, json);
        return json;
    }
 
    @Transaction(intent = Transaction.TYPE.EVALUATE)
    public String ReadAsset(Context ctx, String id) {
        byte[] assetBytes = ctx.getStub().getState(id);
        if (assetBytes == null || assetBytes.length == 0) {
            throw new ChaincodeException(
                "Asset " + id + " does not exist"
            );
        }
        return new String(assetBytes);
    }
 
    @Transaction(intent = Transaction.TYPE.SUBMIT)
    public String UpdateAsset(Context ctx, String id,
                              String newOwner, int newValue) {
        String assetJson = ReadAsset(ctx, id);
        Asset asset = gson.fromJson(assetJson, Asset.class);
 
        asset.setOwner(newOwner);
        asset.setValue(newValue);
        asset.setUpdatedAt(Instant.now().toString());
 
        String json = gson.toJson(asset);
        ctx.getStub().putStringState(id, json);
        return json;
    }
 
    @Transaction(intent = Transaction.TYPE.SUBMIT)
    public void DeleteAsset(Context ctx, String id) {
        byte[] existing = ctx.getStub().getState(id);
        if (existing == null || existing.length == 0) {
            throw new ChaincodeException(
                "Asset " + id + " does not exist"
            );
        }
        ctx.getStub().delState(id);
    }
}

Java's annotation system (@Transaction, @Default) explicitly declares transaction intent, which helps Fabric optimize query routing. The TYPE.EVALUATE intent tells the SDK that ReadAsset doesn't modify state, so it can skip the full endorsement cycle.

How Do You Test Chaincode Before Deployment?

Testing chaincode before deployment catches bugs that would be expensive to fix on a live network. The Hyperledger Fabric Samples repository demonstrates testing patterns for all three languages. Unit tests validate business logic in isolation, while integration tests verify behavior against a running peer.

Go: Unit Testing with MockStub

The fabric-contract-api-go library provides interfaces that are straightforward to mock. Use Go's built-in testing package with mock implementations of TransactionContextInterface and ChaincodeStubInterface:

// chaincode/smartcontract_test.go
package chaincode_test
 
import (
    "encoding/json"
    "testing"
 
    "github.com/hyperledger/fabric-chaincode-go/shim"
    "github.com/hyperledger/fabric-chaincode-go/shimtest"
    "github.com/your-org/asset-chaincode/chaincode"
)
 
func TestCreateAsset(t *testing.T) {
    cc := new(chaincode.SmartContract)
    stub := shimtest.NewMockStub("asset", nil)
 
    // Verify asset doesn't exist before creation
    result := stub.GetState("asset1")
    if result != nil {
        t.Fatal("Expected nil state for non-existent asset")
    }
}

For more sophisticated mocking, use the testify/mock package to simulate specific peer behaviors — network errors, concurrent writes, or endorsement failures.

JavaScript: Testing with Jest

const { Context } = require('fabric-contract-api');
const AssetContract = require('./asset-contract');
 
describe('AssetContract', () => {
    let contract;
    let ctx;
 
    beforeEach(() => {
        contract = new AssetContract();
        ctx = {
            stub: {
                getState: jest.fn(),
                putState: jest.fn(),
                deleteState: jest.fn(),
            },
        };
    });
 
    test('CreateAsset stores a new asset', async () => {
        ctx.stub.getState.mockResolvedValue(Buffer.from(''));
        await contract.CreateAsset(ctx, 'asset1', 'alice', '100');
        expect(ctx.stub.putState).toHaveBeenCalledWith(
            'asset1',
            expect.any(Buffer)
        );
    });
 
    test('CreateAsset rejects duplicate IDs', async () => {
        ctx.stub.getState.mockResolvedValue(
            Buffer.from('{"id":"asset1"}')
        );
        await expect(
            contract.CreateAsset(ctx, 'asset1', 'alice', '100')
        ).rejects.toThrow('already exists');
    });
});

Java: Testing with JUnit and Mockito

@ExtendWith(MockitoExtension.class)
class AssetContractTest {
 
    @Mock Context ctx;
    @Mock ChaincodeStub stub;
 
    AssetContract contract = new AssetContract();
 
    @BeforeEach
    void setup() {
        when(ctx.getStub()).thenReturn(stub);
    }
 
    @Test
    void createAssetSuccess() {
        when(stub.getState("asset1")).thenReturn(new byte[0]);
        String result = contract.CreateAsset(
            ctx, "asset1", "alice", 100
        );
        verify(stub).putStringState(eq("asset1"), anyString());
    }
 
    @Test
    void createAssetDuplicateFails() {
        when(stub.getState("asset1"))
            .thenReturn("{\"id\":\"asset1\"}".getBytes());
        assertThrows(ChaincodeException.class, () ->
            contract.CreateAsset(ctx, "asset1", "alice", 100)
        );
    }
}

Integration Testing

Unit tests validate logic. Integration tests validate behavior against a real peer. Use Fabric's test network (fabric-samples/test-network) to deploy your chaincode and invoke transactions through the Fabric Gateway SDK. This catches issues that mocks miss — serialization bugs, endorsement policy mismatches, and state database quirks.

Testing chaincode before deployment is non-negotiable for production. Go uses shimtest.MockStub for unit tests, JavaScript uses Jest with mocked stubs, and Java uses JUnit with Mockito. The Hyperledger Fabric Samples repository provides reference testing patterns for all three languages.

How Do You Deploy Chaincode with CCaaS?

Chaincode as a Service (CCaaS) is the modern deployment model for Fabric chaincode. Instead of the peer launching chaincode containers, the chaincode runs as an external service that the peer connects to. According to the Fabric 2.5 release notes, CCaaS is the recommended approach for production deployments because it gives operators full control over the chaincode runtime environment.

Why CCaaS Over Traditional Deployment

Traditional deployment packages chaincode into a Docker image that the peer launches and manages. This works for development but creates problems in production: you can't control the container runtime, resource limits, or networking. CCaaS flips the model. You deploy chaincode as a standalone service (container, process, or Kubernetes pod), and the peer connects to it via a configured endpoint.

Benefits of CCaaS:

• Full control over the runtime environment and resource allocation
• Chaincode survives peer restarts without re-instantiation
• Standard deployment tooling (Kubernetes, Docker Compose, systemd)
• Easier debugging — attach a debugger directly to the running process
• Independent scaling of chaincode and peer infrastructure

CCaaS Deployment Steps

Step 1: Build your chaincode as a server. Add the server mode to your main.go:

func main() {
    server := &shim.ChaincodeServer{
        CCID:    os.Getenv("CHAINCODE_CCID"),
        Address: os.Getenv("CHAINCODE_ADDRESS"),
        CC:      &chaincode.SmartContract{},
        TLSProps: shim.TLSProperties{
            Disabled: true,
        },
    }
 
    if err := server.Start(); err != nil {
        log.Panicf("Error starting chaincode server: %v", err)
    }
}

Step 2: Create a connection.json file that tells the peer how to reach your chaincode:

{
    "address": "chaincode-host:9999",
    "dial_timeout": "10s",
    "tls_required": false
}

Step 3: Package only the connection.json (not the chaincode binary) as the chaincode package:

tar cfz code.tar.gz connection.json
tar cfz asset-chaincode.tgz metadata.json code.tar.gz

Step 4: Install, approve, and commit as usual. The peer will connect to your external chaincode service instead of launching a container.

This is how I deploy all production chaincode now. It integrates cleanly with Kubernetes health checks, resource quotas, and rolling updates. The chaincode is just another microservice in your infrastructure.

Ready to deploy your own Fabric network? Book a call with David to discuss your use case, or start deploying now with ChainLaunch.

What Are the Key Security Patterns for Chaincode?

Input validation is the most overlooked chaincode security practice. A Chainalysis 2024 report attributed $2.2 billion in losses to smart contract vulnerabilities and key compromises that year. While permissioned networks have a smaller attack surface than public chains, chaincode still needs defensive coding.

Input Validation

Validate every parameter before writing to the ledger. Never trust client input:

func (s *SmartContract) CreateAsset(
    ctx contractapi.TransactionContextInterface,
    id string, owner string, value int,
) error {
    if len(id) == 0 || len(id) > 64 {
        return fmt.Errorf("asset ID must be 1-64 characters")
    }
    if len(owner) == 0 {
        return fmt.Errorf("owner cannot be empty")
    }
    if value < 0 {
        return fmt.Errorf("value must be non-negative")
    }
    // ... proceed with creation
}

Access Control with Client Identity

Use the Client Identity library to enforce role-based access:

func (s *SmartContract) DeleteAsset(
    ctx contractapi.TransactionContextInterface,
    id string,
) error {
    // Check caller has admin attribute
    err := ctx.GetClientIdentity().AssertAttributeValue("role", "admin")
    if err != nil {
        return fmt.Errorf("caller is not authorized to delete assets")
    }
 
    return ctx.GetStub().DelState(id)
}

Common Vulnerabilities to Avoid

Non-deterministic code: Chaincode must produce identical results across endorsing peers. Avoid time.Now() for business logic (use transaction timestamp instead), random number generation, and external API calls that might return different results.

Range query phantoms: In CouchDB, range queries can return different results on different peers if writes happen between endorsement and commit. Use key-based lookups for endorsement-critical operations.

Unbounded iterations: GetStateByRange("", "") scans the entire state database. In production with millions of keys, this will time out. Always paginate.

For a deeper dive into Fabric's privacy controls that complement chaincode security, see our Hyperledger Fabric private data tutorial.

What Performance Optimizations Matter Most?

Chaincode performance depends more on state access patterns than language speed. The Hyperledger Performance Whitepaper (2024) showed that optimized state access patterns can improve throughput by 3-5x regardless of language choice. The biggest gains come from reducing state reads per transaction and batching writes.

Cross-Language Optimization Principles

1. Minimize GetState calls — Each GetState is a round-trip to the state database. Cache reads within a single transaction.
2. Use composite keys over rich queries — Composite key lookups are O(1). Rich queries scan the database.
3. Batch related writes — Multiple PutState calls in a single transaction are cheaper than multiple transactions.
4. Keep state values small — Large JSON blobs slow serialization. Split into multiple keys if values exceed 100KB.
5. Avoid GetStateByRange without bounds — Always specify start and end keys for range queries.

Go-Specific Optimizations

Pre-allocate slices when you know the expected size. Use json.RawMessage to avoid unnecessary marshal/unmarshal cycles for nested data. Compile with CGO_ENABLED=0 for a fully static binary that runs without libc dependencies.

JavaScript-Specific Optimizations

Avoid deeply nested async/await chains. Use Buffer.from() instead of string concatenation for building state values. Consider using fabric-shim's streaming APIs for large result sets instead of loading everything into memory.

Java-Specific Optimizations

Use putStringState instead of putState with manual byte conversion. Configure JVM heap size appropriately in your Docker container — too small causes frequent garbage collection, too large wastes memory. Consider GraalVM native image compilation for near-instant cold starts.

How Do You Handle Chaincode Upgrades?

Upgrading chaincode follows the same lifecycle as initial deployment — package, install, approve, commit — but with an incremented sequence number. The Fabric documentation specifies that all organizations must approve the new version before it becomes active. This multi-party approval process prevents any single org from pushing breaking changes.

Upgrade Steps

# Package the new version
peer lifecycle chaincode package asset-v2.tar.gz \
  --path ./asset-chaincode \
  --lang golang \
  --label asset_2
 
# Install on endorsing peers
peer lifecycle chaincode install asset-v2.tar.gz
 
# Get the new package ID
peer lifecycle chaincode queryinstalled
 
# Approve with incremented sequence
peer lifecycle chaincode approveformyorg \
  --channelID mychannel \
  --name asset-chaincode \
  --version 2.0 \
  --sequence 2 \
  --package-id asset_2:abc123...
 
# Commit (after all required orgs approve)
peer lifecycle chaincode commit \
  --channelID mychannel \
  --name asset-chaincode \
  --version 2.0 \
  --sequence 2

Data Migration Considerations

Chaincode upgrades can read existing state but should handle backward compatibility. If you change the data model, include migration logic in an Init function or handle both old and new formats in your read operations. Never assume the state database only contains data in the new format — old entries persist.

For a detailed cost analysis of chaincode development and maintenance, see our Hyperledger development cost guide.

FAQ

Which chaincode language delivers the best performance?

Go delivers the highest throughput — approximately 15-30% faster than Java and 30-50% faster than JavaScript in benchmarks using identical business logic. The Hyperledger Performance Whitepaper (2024) measured these differences using standardized workloads. However, state access patterns matter more than language speed. A well-optimized JavaScript chaincode outperforms a poorly written Go one.

Can I mix chaincode languages within a single Fabric network?

Yes. Each chaincode is an independent program, so different chaincodes on the same channel can use different languages. Organization A might deploy an asset-tracking chaincode in Go while Organization B deploys a compliance-reporting chaincode in Java. They coexist on the same channel without conflicts. The peer handles language-specific runtime containers independently.

How do I debug chaincode in development?

For Go, use dlv (Delve debugger) with CCaaS mode. Run the chaincode as an external process and attach the debugger to the listening port. For JavaScript, use --inspect flag with Node.js and connect Chrome DevTools. For Java, use remote debugging with JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005. CCaaS mode makes all of these straightforward.

Can AI generate production-ready chaincode?

AI tools like Claude and Copilot can generate structurally correct chaincode in all three languages, but the output always needs human review. Common issues: missing input validation, non-deterministic code patterns (like using time.Now() for business logic), and incomplete error handling. Use AI to accelerate the first draft, then review for Fabric-specific correctness. Our guide on AI-assisted chaincode development covers the workflow in detail.

What's the maximum chaincode response size?

The default gRPC message size limit is 100 MB, configured via the peer's CORE_PEER_MAXRECVMSGSIZE and CORE_PEER_MAXSENDMSGSIZE environment variables. In practice, responses over a few megabytes indicate a design problem. Paginate large result sets using GetStateByRangeWithPagination or GetQueryResultWithPagination instead of returning everything at once.

Should I use CouchDB or LevelDB as the state database?

LevelDB is the default and performs better for key-based lookups. CouchDB adds rich query support (JSON selector queries) but with additional operational complexity and slightly lower throughput. Use CouchDB if your chaincode needs to query by arbitrary fields. Stick with LevelDB if composite key lookups cover your query patterns — they almost always should.

Conclusion

Go remains the strongest default for Fabric chaincode in 2026. It delivers the best performance, produces the smallest binaries, and aligns with Fabric's own development ecosystem. But "best" is contextual. A team of JavaScript developers will ship faster in Node.js than struggling through Go's learning curve. An enterprise Java shop will integrate more smoothly with existing middleware using Java chaincode.

The patterns that matter across all languages are consistent: validate every input, test before deployment, use CCaaS for production, minimize state reads, and plan for upgrades from day one. The complete CRUD examples in this tutorial give you a working foundation — adapt the asset model to your domain, add your business rules, and build from there.

Start with a running Fabric network using our network creation guide, write your chaincode using the patterns above, and deploy it. For teams that want to accelerate the process, our guide on building a Fabric PoC with Claude Code shows how AI-assisted development fits into the workflow.

Related guides: Create a Hyperledger Fabric Network | AI-Assisted Chaincode Development | Build a Fabric PoC with Claude Code | Fabric Private Data Tutorial | Hyperledger Development Cost Guide

Ready to deploy your own Fabric network? Book a call with David to discuss your use case, or start deploying now with ChainLaunch.

David Viejo is the founder of ChainLaunch and a Hyperledger Foundation contributor. He created the Bevel Operator Fabric project and has been building blockchain infrastructure tooling since 2020.