How to run a Hyperledger Fabric Gateway application

Running a Hyperledger Fabric Gateway application proves that a client identity can connect to a peer gateway, call deployed chaincode, submit ledger updates, and read the committed result. Use it after the local test network and the sample basic chaincode are ready, or before adapting the Gateway client code for another application.

The TypeScript sample uses the Fabric Gateway client API for Node.js. It reads the Org1 user certificate, private key, and peer TLS certificate from the test network, connects to peer0.org1.example.com, and calls the basic chaincode on mychannel.

The sample run initializes assets, queries the ledger, creates a new asset, transfers it asynchronously while waiting for commit status, reads the changed asset, and catches an expected missing-asset error. Keep production identities, hostnames, MSP IDs, channel names, and TLS material out of shared transcripts when replacing the sample values.

1. Change to the Fabric test network directory.

   $ cd fabric-samples/\
   test-network

2. Start a CA-backed test network and create the sample channel.

   $ ./network.sh up createChannel \
     -c mychannel \
     -ca

   The Gateway sample expects CA-generated Org1 user material. The -ca option creates those identities for the default sample network.
   Related: How to run the Hyperledger Fabric test network

3. Deploy the TypeScript asset-transfer-basic chaincode.

   $ ./network.sh deployCC \
     -ccn basic \
     -ccp ../asset-transfer-basic/\
   chaincode-typescript/ \
     -ccl typescript
   Version: 1.0, Sequence: 1
   Chaincode initialization is not required

   The application can use TypeScript, Go, or Java chaincode, but the TypeScript chaincode keeps the sample paths aligned with the TypeScript Gateway application.
   Related: How to deploy Hyperledger Fabric chaincode

4. Change to the asset-transfer sample directory.

   $ cd ../asset-transfer-basic

5. Change to the TypeScript Gateway application directory.

   $ cd application-gateway-typescript

6. Install the application dependencies and build the generated JavaScript.

   $ npm install
   npm run build
   tsc
   added 128 packages
   audited 129 packages in 11s

   The sample package requires Node.js 20 or later and uses npm start to run node dist/app.js.

7. Run the Gateway application.

   $ npm start
    
   channelName:       mychannel
   chaincodeName:     basic
   mspId:             Org1MSP
   peerEndpoint:      localhost:7051
    
   Submit Transaction: InitLedger
   *** Transaction committed successfully
    
   Evaluate Transaction: GetAllAssets
   *** Result: [
     {
       ID: 'asset1',
       Owner: 'Tomoko',
       AppraisedValue: 300
     },
   ##### snipped #####
   ]

   The displayed parameters should match the channel, chaincode, MSP, peer endpoint, and peer TLS host alias for the network being tested.

8. Check the asynchronous transfer section for a successful commit.

   Async Submit Transaction: TransferAsset
   *** Submitted transfer
   *** Owner changed from Tom to Saptha
   *** Waiting for transaction commit
   *** Transaction committed successfully

   submitAsync() returns the smart-contract response first, then getStatus() waits for the transaction commit result.

9. Confirm the final read shows the transferred owner.

   Evaluate Transaction: ReadAsset
   *** Result: {
       AppraisedValue: 1300,
       Color: 'yellow',
       ID: 'asset123',
       Owner: 'Saptha',
       Size: 5
   }

   The asset ID includes a timestamp in the sample application, so the exact asset<number> value changes on each run.
   Related: How to query Hyperledger Fabric chaincode

10. Confirm the expected missing-asset error is caught.

    Submit Transaction: UpdateAsset asset70
    *** Successfully caught the error:
    EndorseError: 10 ABORTED
    ##### snipped #####
    message: asset70 does not exist

    A caught asset70 endorsement error is part of the sample program. A connection error, certificate error, or commit failure means the Gateway endpoint, TLS host alias, identity material, channel, or chaincode name does not match the network.

11. Return to the test network directory.

    $ cd ../../test-network

12. Bring down the sample network when the application test is finished.

    $ ./network.sh down

    This removes the test-network containers, generated organizations, channel artifacts, Docker volumes, and generated chaincode images for the sample network.