CoAP Gateway for Hyperledger Fabric

[bernardo-rf]

This RFC proposes the addition of a Constrained Application Protocol (CoAP) gateway to Hyperledger Fabric. The goal is to enable IoT and resource-constrained devices to interact with Fabric networks using a lightweight, UDP-based protocol. The CoAP gateway will provide a simplified interface for submitting transactions, evaluating chaincode, and receiving events, maintaining security through DTLS encryption and certificate-based authentication.

The current Hyperledger Fabric gRPC gateway has limitations for IoT and resource-constrained devices due to limited memory, processing power, and network bandwidth requirements. Many IoT deployments use UDP-based networks or have unreliable connectivity, making gRPC/HTTP2 impractical. The CoAP gateway addresses these limitations by providing lightweight, UDP-based communication with DTLS security for encrypted and authenticated connections.

Key features include:

• Lightweight, UDP-based communication using CoAP protocol
• DTLS security for encrypted and authenticated connections
• Support for resource-constrained devices
• Event streaming capabilities
• Integration with existing Fabric MSP for device identity management
• Four core endpoints: /evaluate, /endorse, /submit, and /events
• Reuse of existing gRPC gateway logic and protobuf message structures

The CoAP gateway will be implemented as an optional peer service that acts as a protocol converter, translating CoAP requests into appropriate gRPC calls while maintaining the same security model and transaction lifecycle as the existing Fabric gateway.

This enhancement enables new use cases such as supply chain tracking with IoT sensors, smart city applications, and other scenarios requiring direct integration of resource-constrained devices with Fabric networks.

Signed-off-by: Bernardo Figueiredo [email protected] Co-authored-by: Marco Ferreira [email protected] Co-authored-by: Marco Cova [email protected]

[bernardo-rf]

@yacovm @denyeart @manish-sethi @tock-ibm @ale-linux @C0rWin @andrew-coleman @bestbeforetoday @satota2 @pfi79

This is the proper PR related to the RFC proposes adding a CoAP gateway to Fabric for IoT device integration, with the proper checks passed. Please review and provide feedback.

[pfi79]

Thank you for your proposes. I have a few questions.

1. Will you reuse proto files from the fabric-protos project or will you create your own message types?

2. I am interested in how the transaction will be processed by the client (IoT)? It is on the client that the transaction id is generated, the time of the transaction, the nonce, and the transaction is signed. Will you leave it as it is now or change it?

3. You may have already tried something in the form of go code. Could you please provide some parts of the code as an example.

4. In your proposes, you refer to the Fabric SDK. This repository is archived and is not recommended for use. You need to use the fabric-gateway and link to it.

[bestbeforetoday]

The peer Gateway service provides a CommitStatus method in addition to the Evaluate, Endorse, Submit and ChaincodeEvents methods that you have modelled. This is used to check the eventual status of a previously submitted transaction. See the protocol buffer definition and this overview of the Gateway transaction flow. From the RFC description, it sounds like your submit is doing both the Submit and CommitStatus operations.

[bernardo-rf]

@pfi79 Thank you for your questions. Here are the answers.

Thank you for your proposes. I have a few questions.

1. Will you reuse proto files from the fabric-protos project or will you create your own message types?

Yes, the CoAP gateway will reuse the existing proto files from the fabric-protos project. This ensures that the CoAP gateway maintains full compatibility with the existing Fabric gateway ecosystem.

This is stated in the RFC: "Requests and responses use the same protobuf message types as the gRPC service, marshaled into a binary byte array for the CoAP payload."

The RFC specifically mentions using:

• gateway.EvaluateRequest and gateway.EvaluateResponse
• gateway.EndorseRequest and gateway.EndorseResponse
• gateway.SubmitRequest
• gateway.ChaincodeEventsRequest and gateway.ChaincodeEventsResponse

The CoAP gateway will unmarshal incoming CoAP payloads into these standard protobuf messages, process them through the existing gateway logic, and marshal responses back to CoAP format. This approach ensures consistency with the existing gRPC gateway and avoids creating duplicate message definitions. The CoAP gateway acts as a protocol converter, translating CoAP requests into the same protobuf structures used by the gRPC gateway.

2. I am interested in how the transaction will be processed by the client (IoT)? It is on the client that the transaction id is generated, the time of the transaction, the nonce, and the transaction is signed. Will you leave it as it is now or change it?

The current transaction processing model will be maintained. The RFC states: "The client is responsible for packaging all necessary information, such as the channel, chaincode name, and function arguments, within the Protobuf payload, just as they would when using the gRPC gateway directly."

And in the cold chain example: "It extracts the standard Fabric transaction proposal, signed with the device's identity."

This means:

• Transaction ID generation: Remains on the client side
• Transaction timestamp: Handled by the client
• Nonce generation: Client responsibility
• Transaction signing: The device signs the transaction proposal with its identity

The IoT device will use the same transaction preparation logic as any other Fabric client, creating properly formatted protobuf messages that the CoAP gateway can directly forward to the existing Fabric infrastructure.

The CoAP gateway simply acts forwarding the already-prepared and signed protobuf messages to the existing Fabric infrastructure. This maintains the security model where IoT devices are treated as first-class Fabric identities with their own certificates and signing capabilities, ensuring no degradation of Fabric's security properties.

3. You may have already tried something in the form of go code. Could you please provide some parts of the code as an example.

While the RFC doesn't include specific code examples, I can provide a conceptual example based on the design described. This represents the planned implementation approach rather than existing code.

Here's what the implementation would look like using the existing Fabric protobuf definitions

// Example CoAP handler for endorsement
func (h *EndorseHandler) HandleEndorse(w coap.ResponseWriter, req *coap.Request) {
    // Extract protobuf payload from CoAP request
    payload := req.Body()
    
    // Unmarshal the standard Fabric gateway.EndorseRequest
    var endorseReq gateway.EndorseRequest
    if err := proto.Unmarshal(payload, &endorseReq); err != nil {
        w.SetCode(coap.BadRequest)
        w.Write([]byte("Invalid protobuf payload"))
        return
    }
    
    // Authenticate client using DTLS certificate
    clientCert := req.ClientCertificate()
    identity, err := h.authenticator.ValidateCertificate(clientCert)
    if err != nil {
        w.SetCode(coap.Unauthorized)
        return
    }
    
    // Forward to existing gRPC gateway logic
    response, err := h.gatewayService.Endorse(context.Background(), &endorseReq)
    if err != nil {
        w.SetCode(coap.InternalServerError)
        return
    }
    
    // Marshal response back to protobuf
    responseBytes, _ := proto.Marshal(response)
    w.SetCode(coap.Content)
    w.Write(responseBytes)
}


// Example server setup
func NewCoAPGateway(config *Config) *CoAPGateway {
    server := coap.NewServer()
    
    // Register handlers for each endpoint
    server.Handle("/endorse", &EndorseHandler{gatewayService: config.GatewayService})
    server.Handle("/submit", &SubmitHandler{gatewayService: config.GatewayService})
    server.Handle("/commit-status", &CommitStatusHandler{gatewayService: config.GatewayService})
    server.Handle("/evaluate", &EvaluateHandler{gatewayService: config.GatewayService})
    server.Handle("/events", &EventsHandler{gatewayService: config.GatewayService})
    
    return &CoAPGateway{server: server}
}

This implementation demonstrates how the CoAP gateway would integrate with existing Fabric infrastructure while providing the lightweight protocol interface needed for IoT devices.

4. In your proposes, you refer to the Fabric SDK. This repository is archived and is not recommended for use. You need to use the fabric-gateway and link to it.

You raise an excellent point about the Fabric SDK being archived. Let me clarify the context of these references in the RFC.

The RFC uses "Fabric SDK" in two specific contexts, neither of which recommends its use: Historical Problem Description (Line 51): "Historically, this required... use a Fabric SDK to submit a transaction" This just describes a previous approach before the CoAP gateway solution

Conceptual Analogy (Line 57): "Think of it as a specialized application client, like one built with the Fabric SDK, but one that speaks CoAP instead of gRPC" This uses Fabric SDK as a familiar reference point to help developers understand the new concept

The RFC correctly focuses on the current fabric-gateway in all technical sections:

• Uses gateway.EvaluateRequest, gateway.EndorseRequest, etc. (current protobuf definitions)
• Integrates with existing gRPC gateway infrastructure
• References the current gateway architecture

If you prefer, we could update these references to use more generic terms like "Fabric client library" or "existing Fabric client" or "Fabric Gateway" to avoid any confusion about the deprecated SDK. However, the current references serve their intended purpose of explaining historical context and providing conceptual clarity without recommending the use of deprecated libraries.

[bernardo-rf]

@bestbeforetoday Thank you for your question. Here is the answer.

The peer Gateway service provides a CommitStatus method in addition to the Evaluate, Endorse, Submit and ChaincodeEvents methods that you have modelled. This is used to check the eventual status of a previously submitted transaction. See the protocol buffer definition and this overview of the Gateway transaction flow. From the RFC description, it sounds like your submit is doing both the Submit and CommitStatus operations.

You're correct! The current Fabric Gateway service includes a CommitStatus method that is not yet addressed in the CoAP gateway design.

To ensure the CoAP gateway provides the same functionality as the existing gRPC gateway, I propose adding a fifth endpoint to the RFC.

The current CoAP gateway RFC models four endpoints:

• /evaluate - for evaluation requests
• /endorse - for managing endorsements
• /submit - for processing transaction submissions
• /events - for listening to events

My proposal is to update the RFC with the following changes:

1. Add a /commit-status endpoint that accepts a gateway.CommitStatusRequest and returns a gateway.CommitStatusResponse.
2. Clarify the behavior of the /submit endpoint. The RFC should explicitly state whether /submit returns a result upon successful submission to the orderer or waits for the transaction to be committed to the ledger.
3. Update the API documentation to reflect the complete set of gateway methods, ensuring parity with the current gRPC gateway.

This would enable IoT devices to both submit transactions and check their status.