{"id":16814,"library":"fabric-shim-api","title":"Hyperledger Fabric Shim API","description":"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).","status":"active","version":"2.5.8","language":"javascript","source_language":"en","source_url":"https://github.com/hyperledger/fabric-chaincode-node","tags":["javascript","fabric-shim","Hyperledger Fabric","Fabric Shim","typescript"],"install":[{"cmd":"npm install fabric-shim-api","lang":"bash","label":"npm"},{"cmd":"yarn add fabric-shim-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add fabric-shim-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the concrete runtime implementation for the API types defined by this package. Both are typically used together in a chaincode project.","package":"fabric-shim","optional":false}],"imports":[{"note":"Primarily used for type declaration and interface implementation in TypeScript chaincode projects.","wrong":"const { ChaincodeInterface } = require('fabric-shim-api');","symbol":"ChaincodeInterface","correct":"import { ChaincodeInterface } from 'fabric-shim-api';"},{"note":"Represents the chaincode stub, providing methods to interact with the ledger and transaction context. Usually accessed via `stub: Stub` in chaincode methods.","wrong":"const { Stub } = require('fabric-shim-api');","symbol":"Stub","correct":"import { Stub } from 'fabric-shim-api';"},{"note":"Use named imports for `SuccessResponse` and `ErrorResponse` directly from the root module for consistency. `Response` is a union type of these.","wrong":"import { Response } from 'fabric-shim-api/lib/interfaces';","symbol":"Response","correct":"import { SuccessResponse, ErrorResponse, Response } from 'fabric-shim-api';"}],"quickstart":{"code":"import { ChaincodeInterface, Stub, SuccessResponse, ErrorResponse, ChaincodeResponse } from 'fabric-shim-api';\n\nclass MyChaincode implements ChaincodeInterface {\n    async Init(stub: Stub): Promise<ChaincodeResponse> {\n        console.info('=========== Instantiated MyChaincode ===========');\n        return SuccessResponse.newSuccess('Chaincode initialized successfully.');\n    }\n\n    async Invoke(stub: Stub): Promise<ChaincodeResponse> {\n        console.info('=========== Invoked MyChaincode ===========');\n        const ret = stub.getFunctionAndParameters();\n        const method = this[ret.fcn as keyof MyChaincode];\n\n        if (!method) {\n            console.error(`No method found for function: ${ret.fcn}`);\n            return ErrorResponse.newError(`Unknown function: ${ret.fcn}`);\n        }\n\n        try {\n            const payload = await method.apply(this, [stub, ret.params]);\n            return SuccessResponse.newSuccess(payload);\n        } catch (err: any) {\n            console.error(`Error calling function ${ret.fcn}: ${err.message}`);\n            return ErrorResponse.newError(err.message);\n        }\n    }\n\n    private async createAsset(stub: Stub, args: string[]): Promise<Buffer> {\n        if (args.length !== 2) {\n            throw new Error('Incorrect number of arguments. Expecting 2 (assetName, assetValue).');\n        }\n        const [assetName, assetValue] = args;\n        await stub.putState(assetName, Buffer.from(assetValue));\n        return Buffer.from(`Asset ${assetName} created with value ${assetValue}`);\n    }\n}\n\n// For demonstration, typically registered with chaincode-api or shim directly\n// For a real chaincode, you'd usually pass this to start() from 'fabric-shim'\n// For example: chaincode.start(new MyChaincode());\n\nexport { MyChaincode };","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=2.5.3"},{"fix":"Update your chaincode logic to expect a parsed JSON object from `stub.getHistory()` instead of a raw `Buffer`.","message":"The `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.","severity":"breaking","affected_versions":">=2.5.2"},{"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.","message":"A 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`.","severity":"gotcha","affected_versions":"<2.5.6"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=2.5.1 <2.5.7"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: The chaincode is not built with a compatible Node.js version."},{"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`.","cause":"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.","error":"TypeError: stub.getHistory is not a function"},{"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.","cause":"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.","error":"Property 'someMethod' does not exist on type 'ChaincodeInterface'."},{"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.","cause":"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.","error":"Error: 14 UNAVAILABLE: No connection established"}],"ecosystem":"npm","meta_description":null}