@decaf-ts/for-fabric

Hyperledger Fabric Contracts for DECAF

Chaincode-side building blocks for Hyperledger Fabric written in TypeScript. This module provides repositories, CRUD contracts (object and serialized JSON), an ERC20 sample contract, Fabric-backed sequences, event emission, and context-aware logging. It adapts DECAF’s data-access patterns to Fabric’s world-state so you can write smart contracts with the same Repository/Model abstractions used elsewhere in DECAF.

Release docs refreshed on 2025-11-26. See workdocs/reports/RELEASE_NOTES.md for ticket summaries.

Documentation available here

Description

This module focuses on the chaincode (contracts) side of @decaf-ts/for-fabric. It adapts DECAF’s Repository/Model/Adapter abstractions to Hyperledger Fabric’s world state and execution context so you can implement smart contracts with familiar patterns and minimal boilerplate.

Key ideas:

• Keep your domain models as annotated classes (using @decaf-ts/decorator-validation).
• Use a Repository to persist/read/query models through a Fabric-aware Adapter.
• Compose reusable CRUD contracts and utilities instead of hand-writing stub calls.
• Emit first-class Fabric events from repository operations.
• Leverage context-aware logging and typed flags during execution.

Contracts building blocks identified in src/contracts:

1. Core context and types

• FabricContractContext: Extends the generic Context to expose Fabric-specific properties (stub, clientIdentity, logger) and timestamp resolution from the ledger.
• FabricContractFlags: Interface extending RepositoryFlags with stub, clientIdentity and logger for contract calls.

2. Logging

• ContractLogger: MiniLogger-compatible logger bound to the Fabric contract Context. It honors log levels and forwards to the underlying Fabric logger.

3. Adapter and repository

• FabricContractAdapter: Chaincode-side Adapter that implements CRUD, bulk operations, raw Mango queries, result iteration, model preparation/reversion, composite-key prefixes, and sequence creation. Bridges DECAF abstractions to Fabric (ChaincodeStub, ClientIdentity) and CouchDB-style queries.
• FabricContractRepository: Repository for models inside chaincode. Supports create, update, createAll, updateAll, read/readAll, raw queries (Mango), select projections, prefix-based bulk ops, and event emission through an ObserverHandler.
• FabricContractRepositoryObservableHandler: ObserverHandler that emits Fabric events via stub.setEvent using names generated by generateFabricEventName.

4. Sequences

• FabricContractDBSequence: Fabric-backed implementation of Sequence with current, next and range. Stores values in the world state via FabricContractRepository and supports Number or BigInt sequences with configurable startWith and incrementBy.

5. CRUD contracts

• FabricCrudContract: Base smart contract exposing CRUD endpoints (create, read, update, delete, createAll, readAll, updateAll, deleteAll, raw, init, healthcheck) for a model type. Uses DeterministicSerializer and the FabricContractAdapter/Repository behind the scenes and provides logFor(ctx).
• SerializedCrudContract: Same endpoints as FabricCrudContract but takes/returns JSON strings (de)serialized to the model class. This simplifies client interactions and is used in tests.

6. ERC20 sample

• ERC20Token, ERC20Wallet, Allowance: Sample domain models for an ERC20-like token, wallets and allowances.
• FabricStatement<M,R>: A CouchDBStatement bridge that runs Mango queries through FabricContractAdapter, handling primary key projection when needed.
• FabricERC20Contract: A full ERC20 smart contract showcasing repository-based persistence and arithmetic helpers. Implements Initialize, CheckInitialized, TokenName, Symbol, Decimals, TotalSupply, BalanceOf, Transfer, TransferFrom, Approve, Allowance, Mint, Burn, BurnFrom, ClientAccountBalance, ClientAccountID and an internal _transfer helper.

Design notes:

• Deterministic serialization is used to ensure stable bytes for world-state writes.
• onCreate/onCreateUpdate hooks from db-decorators are leveraged by the adapter to set primary keys and creator/owner metadata.
• Mango queries (CouchDB) are used for rich queries via getQueryResultWithPagination.
• Event emission is opt-in per operation type through FabricContractRepositoryObservableHandler’s supportedEvents list.

With these components you can build robust chaincode while keeping code concise, testable, and aligned with DECAF’s architecture.

How to Use

Installation

npm install @decaf-ts/for-fabric

Client-Side Usage

Connecting to a Fabric Network

import { FabricAdapter, PeerConfig } from "@decaf-ts/for-fabric";

// Configure connection to a Fabric peer
const config: PeerConfig = {
  mspId: "Org1MSP",
  peerEndpoint: "localhost:7051",
  channelName: "mychannel",
  chaincodeName: "mycc",
  contractName: "mycontract",
  tlsCertPath: "/path/to/tls/cert",
  certDirectoryPath: "/path/to/cert/dir",
  keyDirectoryPath: "/path/to/key/dir",
  cryptoPath: "/path/to/crypto",
  peerHostAlias: "peer0.org1.example.com",
  caEndpoint: "localhost:7054",
  caTlsCertificate: "/path/to/ca/tls/cert",
  caCert: "/path/to/ca/cert",
  caKey: "/path/to/ca/key",
  ca: "ca.org1.example.com",
};

// Create an adapter instance
const adapter = new FabricAdapter(config, "org1-adapter");

// Use the adapter to interact with the Fabric network
async function createAsset() {
  const asset = { id: "asset1", value: "Asset 1 Value" };
  return await adapter.create("assets", "asset1", asset, {}, mySerializer);
}

async function readAsset(id: string) {
  return await adapter.read("assets", id, mySerializer);
}

async function updateAsset(id: string, newValue: string) {
  const asset = await readAsset(id);
  asset.value = newValue;
  return await adapter.update("assets", id, asset, {}, mySerializer);
}

async function deleteAsset(id: string) {
  return await adapter.delete("assets", id, mySerializer);
}

async function queryAssets(owner: string) {
  const query = {
    selector: {
      owner: owner,
    },
  };
  return await adapter.raw(query, true);
}

Listening for Chaincode Events

import { FabricAdapter, FabricDispatch } from "@decaf-ts/for-fabric";

async function setupEventListener(config: PeerConfig) {
  // Create a client
  const client = await FabricAdapter.getClient(config);

  // Create a dispatch instance
  const dispatch = new FabricDispatch(client);

  // Configure the dispatch with peer configuration
  dispatch.configure(config);

  // Register an observer for a specific table and event
  dispatch.observe("assets", "create", (id) => {
    console.log(`Asset created: ${id}`);
    // Fetch the new asset or update UI
  });

  // Start listening for events
  await dispatch.start();

  // When done, close the connection
  // await dispatch.close();
}

Working with Identities and Certificates

import {
  getIdentity,
  getSigner,
  readFile,
  getCAUser,
} from "@decaf-ts/for-fabric";

async function setupIdentity() {
  // Read a certificate file
  const tlsCert = await readFile("/path/to/tls/cert");

  // Get an identity from a certificate directory
  const identity = await getIdentity("Org1MSP", "/path/to/cert/dir");

  // Get a signer from a key directory
  const signer = await getSigner("/path/to/key/dir");

  // Create a CA user
  const user = await getCAUser(
    "user1",
    privateKeyPem,
    certificatePem,
    "Org1MSP"
  );

  return { identity, signer, user };
}

Chaincode Development

Creating a Model

import { Model, id, property, table } from "@decaf-ts/decorator-validation";

@table("assets")
export class Asset extends Model {
  @id()
  id: string;

  @property()
  value: string;

  @property()
  owner: string;

  @property()
  createdAt: number;
}

Creating a CRUD Contract

import { FabricCrudContract } from "@decaf-ts/for-fabric";
import { Context, Contract, Info, Transaction } from "fabric-contract-api";
import { Asset } from "./asset";

@Info({
  title: "AssetContract",
  description: "Smart contract for trading assets",
})
export class AssetContract extends FabricCrudContract<Asset> {
  constructor() {
    super("AssetContract", Asset);
  }

  // The base class already provides standard CRUD operations:
  // create, read, update, delete, createAll, readAll, updateAll, deleteAll

  // Add custom methods as needed
  @Transaction()
  async getAssetHistory(ctx: Context, id: string): Promise<any[]> {
    const stub = ctx.stub;
    const iterator = await stub.getHistoryForKey(id);

    const results = [];
    let result = await iterator.next();

    while (!result.done) {
      const value = result.value;
      results.push({
        txId: value.txId,
        timestamp: value.timestamp,
        value: JSON.parse(value.value.toString("utf8")),
      });

      result = await iterator.next();
    }

    await iterator.close();
    return results;
  }

  @Transaction()
  async transferAsset(
    ctx: Context,
    id: string,
    newOwner: string
  ): Promise<Asset> {
    const asset = await this.read(ctx, id);
    asset.owner = newOwner;
    return await this.update(ctx, asset);
  }
}

Using the Contract Adapter Directly

import { FabricContractAdapter } from "@decaf-ts/for-fabric";
import { Context, Contract, Transaction } from "fabric-contract-api";

export class CustomContract extends Contract {
  private adapter: FabricContractAdapter;

  constructor() {
    super("CustomContract");
    this.adapter = new FabricContractAdapter();
  }

  @Transaction()
  async createRecord(ctx: Context, id: string, data: string): Promise<any> {
    const record = { id, data, timestamp: Date.now() };
    return await this.adapter.create(
      "records",
      id,
      record,
      {},
      { stub: ctx.stub, logger: ctx.logging }
    );
  }

  @Transaction(false)
  async queryRecords(ctx: Context, owner: string): Promise<any[]> {
    const query = {
      selector: {
        owner: owner,
      },
    };

    return await this.adapter.raw(query, true, {
      stub: ctx.stub,
      logger: ctx.logging,
    });
  }
}

Emitting and Handling Events

import {
  FabricContractRepositoryObservableHandler,
  generateFabricEventName,
  parseEventName,
} from "@decaf-ts/for-fabric";
import { Context } from "fabric-contract-api";
import { OperationKeys } from "@decaf-ts/db-decorators";

// In chaincode: Emit an event
async function emitEvent(ctx: Context, tableName: string, id: string) {
  const handler = new FabricContractRepositoryObservableHandler();
  const logger = ctx.logging.getLogger("EventHandler");

  await handler.updateObservers(logger, tableName, OperationKeys.CREATE, id, {
    stub: ctx.stub,
  });
}

// In client: Parse an event name
function handleEvent(eventName: string, payload: Buffer) {
  const { table, event, owner } = parseEventName(eventName);
  const data = JSON.parse(payload.toString());

  console.log(`Received ${event} event for ${table} with ID ${data.id}`);
  if (owner) {
    console.log(`Event owner: ${owner}`);
  }
}

For more detailed examples and API documentation, refer to the API Reference.

Contracts APIs (Chaincode)

The following examples are based on the contracts in for-fabric/src/contracts and reflect the patterns used by the unit/integration tests.

FabricCrudContract

Description: Base contract exposing CRUD endpoints for a model class. It uses Repository and DeterministicSerializer under the hood.

import { Context, Transaction, Contract } from "fabric-contract-api";
import { model, ModelArg, required } from "@decaf-ts/decorator-validation";
import { BaseModel, pk } from "@decaf-ts/core";
import { FabricCrudContract } from "@decaf-ts/for-fabric/contracts";

@model()
class Person extends BaseModel {
  @pk({ type: "Number" })
  id!: number;
  @required() name!: string;
  constructor(arg?: ModelArg<Person>) {
    super(arg);
  }
}

export class PersonContract extends FabricCrudContract<Person> {
  constructor() {
    super("PersonContract", Person);
  }

  @Transaction(false)
  async ping(ctx: Context): Promise<string> {
    // Uses FabricCrudContract.logFor
    this.logFor(ctx).info("ping");
    return "pong";
  }
}

Usage in tests: see tests/unit/contracts.test.ts pattern where a SerializedCrudContract subclass is exercised; FabricCrudContract is similar but takes/returns objects instead of JSON strings.

SerializedCrudContract

Description: Same endpoints as FabricCrudContract but takes and returns JSON strings. Useful for simple clients. Based on tests/unit/contracts.test.ts.

import { Context } from "fabric-contract-api";
import { model, ModelArg, required } from "@decaf-ts/decorator-validation";
import { BaseModel, pk } from "@decaf-ts/core";
import { SerializedCrudContract } from "@decaf-ts/for-fabric/contracts";

@model()
class TestModel extends BaseModel {
  @pk({ type: "Number" }) id!: number;
  @required() name!: string;
  @required() nif!: string;
  constructor(arg?: ModelArg<TestModel>) {
    super(arg);
  }
}

export class TestModelContract extends SerializedCrudContract<TestModel> {
  constructor() {
    super("TestModelContract", TestModel);
  }
}

// Example invocation (mirrors unit test usage)
async function createExample(contract: TestModelContract, ctx: Context) {
  const payload = new TestModel({
    name: "Alice",
    nif: "123456789",
  }).serialize();
  const resultJson = await contract.create(ctx, payload);
  const created = new TestModel(JSON.parse(resultJson));
  return created;
}

FabricContractRepository

Description: Chaincode-side repository used inside contract methods to persist and query models.

import { Context } from "fabric-contract-api";
import { Repo } from "@decaf-ts/core";
import { model, required, ModelArg } from "@decaf-ts/decorator-validation";
import { BaseModel, pk } from "@decaf-ts/core";
import { FabricContractRepository } from "@decaf-ts/for-fabric/contracts";

@model()
class Asset extends BaseModel {
  @pk() id!: string;
  @required() owner!: string;
  constructor(arg?: ModelArg<Asset>) {
    super(arg);
  }
}

export class AssetContract extends Contract {
  private repo: Repo<Asset, any, any, any, any>;
  constructor() {
    super("AssetContract");
    this.repo = new FabricContractRepository<Asset>(
      new (require("@decaf-ts/for-fabric").contracts.FabricContractAdapter)(),
      Asset
    );
  }

  @Transaction()
  async Create(ctx: Context, id: string, owner: string): Promise<void> {
    const m = new Asset({ id, owner });
    await this.repo.create(m, ctx as any);
  }

  @Transaction(false)
  async Read(ctx: Context, id: string): Promise<Asset> {
    return this.repo.read(id, ctx as any);
  }

  @Transaction(false)
  async QueryByOwner(ctx: Context, owner: string): Promise<Asset[]> {
    return this.repo.raw({ selector: { owner } } as any, true, ctx as any);
  }
}

FabricContractDBSequence

Description: World-state backed sequences for generating incremental values.

import { Context } from "fabric-contract-api";
import { FabricContractDBSequence } from "@decaf-ts/for-fabric/contracts";
import { FabricContractAdapter } from "@decaf-ts/for-fabric/contracts";

const adapter = new FabricContractAdapter();

export class OrderContract extends Contract {
  private orderSeq = new FabricContractDBSequence(
    {
      name: "orderSeq",
      type: "Number",
      startWith: 1,
      incrementBy: 1,
    },
    adapter
  );

  @Transaction()
  async CreateOrder(ctx: Context): Promise<number> {
    const next = await this.orderSeq.next(ctx as any);
    // use next as order id
    return next as number;
  }

  @Transaction(false)
  async NextRange(ctx: Context, count: number): Promise<number[]> {
    return (await this.orderSeq.range(count, ctx as any)) as number[];
  }
}

FabricStatement<M,R>

Description: Bridge to run Mango queries through the Fabric adapter and get typed models back; used internally by repositories and also directly in advanced cases. See tests/unit/erc20conttract.test.ts mocking CouchDBStatement processing.

import { FabricStatement } from "@decaf-ts/for-fabric/contracts";
import { FabricContractAdapter } from "@decaf-ts/for-fabric/contracts";
import { FabricContractContext } from "@decaf-ts/for-fabric/contracts";
import { MangoQuery } from "@decaf-ts/for-couchdb";
import { Model } from "@decaf-ts/decorator-validation";

class MyModel extends Model {}

const adapter = new FabricContractAdapter();

async function query(ctx: FabricContractContext) {
  const stmt = new FabricStatement<MyModel, MyModel[]>(adapter, ctx);
  const models = await stmt.raw<MyModel[]>({
    selector: { type: "MyModel" },
  } as MangoQuery);
  return models;
}

ContractLogger

Description: Context-aware logger bound to Fabric’s Context, honoring log levels.

import { Context, Transaction } from "fabric-contract-api";
import { Contract } from "fabric-contract-api";
import { ContractLogger } from "@decaf-ts/for-fabric/contracts";

export class LoggableContract extends Contract {
  @Transaction()
  async DoWork(ctx: Context): Promise<void> {
    const log = new ContractLogger(
      "LoggableContract",
      { level: "info" },
      ctx as any
    );
    log.info("Starting work");
    // ... work ...
    log.debug("Finished");
  }
}

FabricContractRepositoryObservableHandler

Description: Emits Fabric events for repository operations. You can also use it directly to emit a custom event.

import { FabricContractRepositoryObservableHandler } from "@decaf-ts/for-fabric/contracts";
import { OperationKeys } from "@decaf-ts/db-decorators";
import { FabricContractContext } from "@decaf-ts/for-fabric/contracts";
import { MiniLogger } from "@decaf-ts/logging";

async function emitExample(ctx: FabricContractContext) {
  const handler = new FabricContractRepositoryObservableHandler();
  const log = new MiniLogger("obs");
  await handler.updateObservers(
    log as any,
    "assets",
    OperationKeys.CREATE,
    "asset1",
    ctx
  );
}

FabricContractContext

Description: Access Fabric-specific context inside contracts.

import { FabricContractContext } from "@decaf-ts/for-fabric/contracts";

function readContext(ctx: FabricContractContext) {
  const ts = ctx.timestamp; // Date from stub.getDateTimestamp()
  const id = ctx.identity.getID();
  ctx.logger.info(`Tx by ${id} at ${ts.toISOString()}`);
}

FabricERC20Contract (sample)

Description: Full ERC20 implementation used in tests (see tests/unit/erc20conttract.test.ts).

import { FabricERC20Contract } from "@decaf-ts/for-fabric/contracts";
import { FabricContractContext } from "@decaf-ts/for-fabric/contracts";

const contract = new FabricERC20Contract("TestToken");

async function initAndRead(ctx: FabricContractContext) {
  const created = await contract.Initialize(ctx, "TestToken", "TT", 18);
  if (created) {
    const name = await contract.TokenName(ctx);
    const decimals = await contract.Decimals(ctx);
    return { name, decimals };
  }
  throw new Error("Init failed");
}

Notes on tests as examples

• tests/unit/contracts.test.ts shows creating a SerializedCrudContract and calling create(ctx, jsonPayload) with a mocked Fabric Context.
• tests/unit/erc20conttract.test.ts demonstrates initializing the ERC20 contract and reading TokenName.
• tests/integration/Serialized-Contract.test.ts shows end-to-end JSON-based CRUD flows via the serialized contract, including create, read, update and rich queries.

These patterns are mirrored in the examples above to ensure correctness and consistency with the repository’s test suite.

Coding Principles

• group similar functionality in folders (analog to namespaces but without any namespace declaration)
• one class per file;
• one interface per file (unless interface is just used as a type);
• group types as other interfaces in a types.ts file per folder;
• group constants or enums in a constants.ts file per folder;
• group decorators in a decorators.ts file per folder;
• always import from the specific file, never from a folder or index file (exceptions for dependencies on other packages);
• prefer the usage of established design patters where applicable:
  • Singleton (can be an anti-pattern. use with care);
  • factory;
  • observer;
  • strategy;
  • builder;
  • etc;

Release Documentation Hooks

Stay aligned with the automated release pipeline by reviewing Release Notes and Dependencies after trying these recipes (updated on 2025-11-26).

Related

Social

Languages

Getting help

If you have bug reports, questions or suggestions please create a new issue.

Contributing

I am grateful for any contributions made to this project. Please read this to get started.

Supporting

The first and easiest way you can support it is by Contributing. Even just finding a typo in the documentation is important.

Financial support is always welcome and helps keep both me and the project alive and healthy.

So if you can, if this project in any way. either by learning something or simply by helping you save precious time, please consider donating.

License

This project is released under the Mozilla Public License 2.0.

By developers, for developers...