-
Notifications
You must be signed in to change notification settings - Fork 140
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Mark Blackman <[email protected]> Signed-off-by: mab <[email protected]> Signed-off-by: Michael Garber <[email protected]> Co-authored-by: Mark Blackman <[email protected]> Co-authored-by: Joseph S. <[email protected]> Co-authored-by: Michael Garber <[email protected]>
- Loading branch information
4 people
authored
Oct 15, 2024
1 parent
47fbc5a
commit 0b4c6a6
Showing
1 changed file
with
180 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,180 @@ | ||
| --- | ||
| hip: 1046 | ||
| title: Adding support for gRPC-Web proxy endpoints to the Address Book | ||
| author: Joseph Sinclair <Joseph Sinclair<@jsync-swirlds>, Mark Blackman <[email protected]>, Simi Hunjan <[email protected]> | ||
| working-group: Mike Cave <[email protected]>, Alex Popowycz <[email protected]> | ||
| requested-by: Hedera | ||
| type: Standards Track | ||
| category: Core | ||
| needs-council-approval: Yes | ||
| status: Last Call | ||
| last-call-date-time: 2024-10-29T07:00:00Z | ||
| created: 2024-09-18 | ||
| updated: 2024-10-15 | ||
| --- | ||
|
|
||
| ## Abstract | ||
|
|
||
| Frontend applications using the Hedera JavaScript SDK face challenges due to browser security sandbox rules, which block mixed content (i.e., HTTP requests from HTTPS pages) and do not permit direct gRPC requests. Browsers also require TLS endpoints to be signed by trusted certificate authorities, necessitating fully qualified domain names (FQDNs). | ||
|
|
||
| Currently, gRPC-Web servers work around these limitations, but the endpoints are not supported in the Hedera Address Book. To circumvent this, gRPC-Web endpoints are hard-coded in the JavaScript SDK, which is neither scalable nor efficient. This approach requires manual updates and coordination, which will become increasingly problematic as Hedera decentralizes and more independent nodes operate. | ||
|
|
||
| To address this issue, we propose enhancing the Hedera address book to include gRPC-Web endpoint information, allowing the JavaScript SDK to dynamically determine the appropriate endpoints | ||
|
|
||
| ## Motivation | ||
|
|
||
| Hedera offers a gRPC API for various transactions, accessible through SDKs. These SDKs support both backend applications (e.g., node.js) and frontend web applications and plug-ins. Backend applications can connect directly to the network proxies' gRPC endpoint. However, frontend applications must comply with browser security sandbox rules, which block mixed content (i.e., HTTP requests from HTTPS pages) and do not permit the low-level HTTP2 access required for direct gRPC requests. | ||
|
|
||
| Therefore frontend applications and web plug-ins using the Hedera JavaScript SDK face challenges due to browser security restrictions. This necessitates the use of gRPC-Web proxy servers with TLS endpoints signed by trusted certificate authorities, which require fully qualified domain names (FQDNs). | ||
|
|
||
| Presently, gRPC-Web server endpoints are not supported in the Hedera Address Book. To work around this gRPC-Web endpoints are hard-coded in the JavaScript SDK. This is not a scalable or efficient solution as it requires manual updates and coordination. The problem will only get worse as Hedera continues decentralization of the network and independent node operation, where this coordination is not possible. | ||
|
|
||
| We propose enhancing the Hedera address book to include gRPC-Web endpoint information, allowing the JavaScript SDK to dynamically determine the appropriate endpoints. This will be achieved by: | ||
|
|
||
| 1. **Extending the Address Book Schema**: Modify the address book schema to include entries for gRPC-Web endpoints. | ||
| 2. **Dynamic Discovery**: Update the JavaScript SDK to dynamically retrieve the gRPC-Web endpoints from the address book. | ||
| 3. **Query Availability**: Update the Mirror Node to recognize gRPC-Web entries in the address book and make those entries available for the SDK to query. | ||
|
|
||
| By implementing these changes, we can ensure that frontend applications can securely and efficiently connect to the Hedera network using dynamically discovered, decentralized TLS endpoints. This will improve the network's resilience, scalability, and overall user experience. | ||
|
|
||
| ## Rationale | ||
|
|
||
| Given that this proposal involves an incremental change to the already existing Hedera Address Book, the design is straightforward. The primary goal is to enhance the address book to include gRPC-Web endpoint information, allowing frontend applications to dynamically determine the appropriate endpoints. | ||
|
|
||
| *Why:* Updating the JavaScript SDK to dynamically retrieve gRPC-Web endpoints from the address book eliminates the need for hard-coded endpoints. This design decision enhances flexibility and scalability, allowing frontend applications to adapt to changes in the network configuration without requiring manual updates. | ||
|
|
||
| *Alternatives Considered:* Another alternative was to continue with the current practice of hard-coding endpoints within the SDK. However, this method is not sustainable as it requires frequent updates and coordination, particularly as Hedera continues to decentralize. Dynamic discovery provides a more robust and future-proof solution. | ||
|
|
||
| ## User stories | ||
|
|
||
| ## | ||
|
|
||
| 1. As a Frontend Developer, I want the Hedera JavaScript SDK to dynamically retrieve gRPC-Web endpoints, so that my web application can securely connect to the Hedera network even as gRPC-Web endpoints change over time. | ||
|
|
||
| Acceptance Criteria: | ||
|
|
||
| - The SDK retrieves the gRPC-Web endpoints from the address book automatically. | ||
| - The application connects securely using the latest TLS endpoints. | ||
| - Any changes in the network configuration are reflected without requiring SDK updates. | ||
| 2. As a gRPC-Web Node Operator, I want to update the FQDN for my node’s endpoint in the address book, so that developers can automatically use the correct, secure endpoint without needing manual intervention. | ||
|
|
||
| Acceptance Criteria: | ||
|
|
||
| - Node operator can update gRPC-Web endpoint in the address book | ||
| - The updated endpoint is propagated to all frontend applications using the Hedera JavaScript SDK. | ||
| - The process is simple and does not require extensive coordination with SDK maintainers | ||
| 3. As an Hedera community member I want to run my own gRPC-Web node for my consensus node and make it visible to the community to assist in growing the network. | ||
|
|
||
| Acceptance Criteria: | ||
|
|
||
| - A community member can launch a gRPC-Web node without external interaction. | ||
| - A community member can submit a request to have their gRPC-Web node added to the network address book. | ||
|
|
||
| ## Specification | ||
|
|
||
| The dynamic address book stores an entry in state for each node (only consensus, currently). This HIP proposes to extend that “address book” concept to include gRPC-Web node endpoints as an additional field of the `Node` entry. The expectation is that these additional node endpoints will be managed with the same `nodeCreate`, `nodeUpdate`, and `nodeDelete` transactions that manage the other endpoints for consensus nodes. The only changes needed are one additional field in the `NodeCreateTransactionBody`, the same field in `NodeUpdateTransactionBody`, and a matching additional field in the `Node` entry in state. | ||
|
|
||
| Any entity wishing to operate a gRPC-Web proxy node would request to have that node added to the network address book via a `nodeCreate` (which, initially, requires council approval), and would manage that node via `nodeUpdate` as needed to maintain current and up-to-date information for the service endpoints of that node. | ||
|
|
||
| ### Protobufs | ||
|
|
||
| Add a new field to `NodeCreateTransactionBody`. | ||
|
|
||
| ```protobuf | ||
| message NodeCreateTransactionBody { | ||
| ... | ||
| /** | ||
| * An administrative key controlled by the node operator. | ||
| */ | ||
| proto.Key admin_key = 7; | ||
| /** | ||
| * A web proxy for gRPC from non-gRPC clients. | ||
| */ | ||
| proto.ServiceEndpoint grpc_proxy_endpoint = 8;** | ||
| } | ||
| ``` | ||
|
|
||
| Add a new field to `NodeUpdateTransactionBody`. | ||
|
|
||
| ```protobuf | ||
| message NodeUpdateTransactionBody { | ||
| ... | ||
| /** | ||
| * An administrative key controlled by the node operator. | ||
| */ | ||
| proto.Key admin_key = 8; | ||
| /** | ||
| * A web proxy for gRPC from non-gRPC clients. | ||
| */ | ||
| proto.ServiceEndpoint grpc_proxy_endpoint = 9;** | ||
| } | ||
| ``` | ||
|
|
||
| Partial detail for updates to the `Node` message in state. | ||
|
|
||
| ```protobuf | ||
| /** | ||
| * A single address book node in the network state. | ||
| */ | ||
| message Node { | ||
| ... | ||
| /** | ||
| * An administrative key controlled by the node operator. | ||
| */ | ||
| proto.Key admin_key = 10; | ||
| /** | ||
| * A web proxy for gRPC from non-gRPC clients. | ||
| */ | ||
| proto.ServiceEndpoint grpc_proxy_endpoint = 11;** | ||
| } | ||
| ``` | ||
| new NodeCreateTransaction() | ||
| .... | ||
| .setNodeType () | ||
| ... | ||
|
|
||
| ## Backwards Compatibility | ||
|
|
||
| Initially, there should be no change or impact to existing users of the SDKs and gRPC-Web nodes. | ||
| The current set of nodes will remain available at the current addresses. After all SDKs are migrated to use dynamic lookup of the addresses via the mirror node APIs, the existing nodes are expected to remain at the current addresses for some time, but may, eventually, begin to migrate. Clients using SDKs should adopt the new SDK versions that support dynamic address lookup within this time period. Clients not using SDKs to access the gRPC-Web nodes should also migrate to look up the node addresses via the mirror node APIs in the same time period. | ||
| Any client that chooses to continue using the legacy approach of manually maintaining a fixed static list of gRPC-Web nodes may continue to do so, with the constraint that those entities may need to make more frequent updates to their static lists, but the information for those updates will be available from the mirror node. | ||
|
|
||
| ## Security Implications | ||
|
|
||
| There are no known security issues prevented or created by this HIP. | ||
|
|
||
| SDK clients _may_ be more resilient against certain highly sophisticated | ||
| forms of interception; though the practical value of preventing such | ||
| actions is extremely low. | ||
|
|
||
| ## How to Teach This | ||
|
|
||
| Address Book documentation will need to be updated to reflect the new field. | ||
|
|
||
| ## Reference Implementation | ||
|
|
||
| The reference implementation must be complete before any HIP is given the status of “Final”. The final implementation must include test code and documentation. | ||
|
|
||
| ## Rejected Ideas | ||
|
|
||
| Configuration on the consensus nodes, with the same data configured for the SDK. | ||
|
|
||
| An Hedera File System (HFS) file containing the list in a JSON document. | ||
| This would require Mirror Node to read that file and offer an API to query the contents. | ||
|
|
||
| ## Open Issues | ||
|
|
||
| No open issues | ||
|
|
||
| ## References | ||
|
|
||
| https://github.com/hashgraph/hedera-grpcWeb-proxy | ||
|
|
||
| ## Copyright/license | ||
|
|
||
| This document is licensed under the Apache License, Version 2.0 -- see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0) |