Registry / type-stubs / fabric-shim-api

fabric-shim-api

JSON →
library2.5.8jsnpmunverified

The `fabric-shim-api` package provides the Node.js API for Hyperledger Fabric chaincode shim, facilitating communication between endorsing peers and user-provided chaincodes. Its primary role is to offer TypeScript type definitions for the `fabric-shim` module, and it serves as a dependency for `fabric-contract-api`, enabling the use of annotations in client applications without pulling in unnecessary runtime dependencies. The current stable version is 2.5.8, part of the v2.5 LTS series. Releases typically follow the Hyperledger Fabric LTS cadence, with point releases addressing fixes and dependency updates. Key differentiators include its lightweight nature as a type-only package, its integral role in the Fabric Node.js chaincode ecosystem, and its support for modern Node.js runtimes (currently Node 22 for the latest versions).

npm install fabric-shim-api
INSTALL
IMPORT
SIG · FABRIC-SHIM-API
F
fabric-shim-api
type-stubsjavascriptv2.5.8
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ChaincodeInterface
import { ChaincodeInterface } from 'fabric-shim-api';
const { ChaincodeInterface } = require('fabric-shim-api');
Primarily used for type declaration and interface implementation in TypeScript chaincode projects.
Stub
import { Stub } from 'fabric-shim-api';
const { Stub } = require('fabric-shim-api');
Represents the chaincode stub, providing methods to interact with the ledger and transaction context. Usually accessed via `stub: Stub` in chaincode methods.
Response
import { SuccessResponse, ErrorResponse, Response } from 'fabric-shim-api';
import { Response } from 'fabric-shim-api/lib/interfaces';
Use named imports for `SuccessResponse` and `ErrorResponse` directly from the root module for consistency. `Response` is a union type of these.

Demonstrates a basic Hyperledger Fabric chaincode in TypeScript, implementing `ChaincodeInterface` with `Init` and `Invoke` methods, and a simple `createAsset` private function. It shows how to interact with the `Stub` and return appropriate `ChaincodeResponse` objects.

import { ChaincodeInterface, Stub, SuccessResponse, ErrorResponse, ChaincodeResponse } from 'fabric-shim-api'; class MyChaincode implements ChaincodeInterface { async Init(stub: Stub): Promise<ChaincodeResponse> { console.info('=========== Instantiated MyChaincode ==========='); return SuccessResponse.newSuccess('Chaincode initialized successfully.'); } async Invoke(stub: Stub): Promise<ChaincodeResponse> { console.info('=========== Invoked MyChaincode ==========='); const ret = stub.getFunctionAndParameters(); const method = this[ret.fcn as keyof MyChaincode]; if (!method) { console.error(`No method found for function: ${ret.fcn}`); return ErrorResponse.newError(`Unknown function: ${ret.fcn}`); } try { const payload = await method.apply(this, [stub, ret.params]); return SuccessResponse.newSuccess(payload); } catch (err: any) { console.error(`Error calling function ${ret.fcn}: ${err.message}`); return ErrorResponse.newError(err.message); } } private async createAsset(stub: Stub, args: string[]): Promise<Buffer> { if (args.length !== 2) { throw new Error('Incorrect number of arguments. Expecting 2 (assetName, assetValue).'); } const [assetName, assetValue] = args; await stub.putState(assetName, Buffer.from(assetValue)); return Buffer.from(`Asset ${assetName} created with value ${assetValue}`); } } // For demonstration, typically registered with chaincode-api or shim directly // For a real chaincode, you'd usually pass this to start() from 'fabric-shim' // For example: chaincode.start(new MyChaincode()); export { MyChaincode };
Debug
Known issues
breakingThe Node.js runtime requirement for chaincode has progressively increased. Fabric chaincodes using this shim API now require Node.js >=18, with recent versions (2.5.5+) targeting Node 20, and the latest v2.5.8+ targeting Node 22. Older Node.js versions will not be supported or may lead to runtime errors.
fix
Ensure your chaincode Docker images and development environment use Node.js version 18 or higher. For latest stability and features, use Node 20 or Node 22 as specified in the changelog for your target shim-api version.
affects: >=2.5.3
breakingThe `getHistory` API in the `Stub` interface was fixed in v2.5.2 to correctly return a JSON object rather than a raw byte buffer. Chaincodes relying on the previous raw buffer return for `getHistory` will need to adjust their parsing logic.
fix
Update your chaincode logic to expect a parsed JSON object from `stub.getHistory()` instead of a raw `Buffer`.
affects: >=2.5.2
gotchaA vulnerability (CVE-2024-37168) in the underlying `grpc-js` dependency was addressed in v2.5.6. While `fabric-shim-api` itself is a type package, the runtime `fabric-shim` depends on `grpc-js`.
fix
Upgrade to `fabric-shim-api@2.5.6` or higher (along with `fabric-shim`) to mitigate the `grpc-js` vulnerability. Prioritize updating to the latest stable release.
affects: <2.5.6
gotchaThe `grpc-js` dependency had its version strictly locked to 1.8.1 in v2.5.1 due to issues, but this constraint was relaxed in v2.5.7. This could lead to different `grpc-js` versions being resolved depending on your `fabric-shim` version and other dependencies, potentially causing subtle behavioral differences or conflicts.
fix
For optimal compatibility and to benefit from latest fixes, upgrade `fabric-shim-api` and `fabric-shim` to the latest v2.5.x LTS release (e.g., 2.5.8+), which incorporates the relaxed constraint and recent `grpc-js` updates.
affects: >=2.5.1 <2.5.7
Errors
Common errors & fixes
Error: The chaincode is not built with a compatible Node.js version.
The Node.js version used to build or run the chaincode container is older than the minimum required by the `fabric-shim` and `fabric-shim-api` versions.
fix
Update the Node.js version in your chaincode Dockerfile and local development environment to Node.js 18 or higher. For recent shim versions (2.5.5+), use Node.js 20 or Node.js 22.
TypeError: stub.getHistory is not a function
Using an outdated `fabric-shim-api` (or `fabric-shim`) version that predates the introduction or stabilization of the `getHistory` API, or an incorrect `Stub` type.
fix
Ensure you are using `fabric-shim-api` and `fabric-shim` versions 2.5.2 or higher. Verify your `stub` variable is correctly typed as `Stub` from `fabric-shim-api`.
Property 'someMethod' does not exist on type 'ChaincodeInterface'.
Attempting to call a custom chaincode method directly via `this[funcName]` without proper type assertions or ensuring the method is publicly accessible on the `ChaincodeInterface` implementation.
fix
In your `Invoke` method, safely access custom functions using `(this as any)[ret.fcn]` or implement type guards to ensure the method exists and is callable. Alternatively, define an interface that extends `ChaincodeInterface` and includes your custom methods.
Error: 14 UNAVAILABLE: No connection established
Issues with the gRPC communication layer between the chaincode and the peer, often due to network configuration, misconfigured `CORE_CHAINCODE_ID_NAME` or `CORE_PEER_ADDRESS`, or incompatible `grpc-js` versions.
fix
Check network connectivity between the chaincode container and the peer. Verify `CORE_CHAINCODE_ID_NAME` and `CORE_PEER_ADDRESS` environment variables are correctly set. Ensure `fabric-shim` and `grpc-js` versions are compatible; upgrading to the latest `fabric-shim` (2.5.8+) often resolves underlying gRPC issues.
Upgrade
Version history
2.5.8latest on npm
Audit
Dependencies
fabric-shimrequiredProvides the concrete runtime implementation for the API types defined by this package. Both are typically used together in a chaincode project.
Agent activity
53 hits · last 30 days
node
46
OpenAI (training)
1
Resources
fabric-shim-api — npm install fabric-shim-api · libregistry