From 6e1d828828a4374b576196b95a73a679c2d7f990 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 6 May 2026 16:59:38 +0200 Subject: [PATCH 1/2] docs: add edge infrastructure concept page (API boundary nodes, HTTP gateway, asset certification) Migrates 4 Learn Hub articles from the "ICP and the Internet" section into a single docs/concepts/edge-infrastructure.md page covering API boundary nodes, HTTP gateways, the HTTP Gateway Protocol request lifecycle, and asset certification using chain-key cryptography and certified variables. Adds a "See also" link at the top of docs/references/http-gateway-spec.md. --- .../asset-certification.md | 27 -------- .../http-gateway-protocol.md | 47 ------------- .../icp-and-the-internet.md | 25 ------- .../icp-edge-infrastructure.md | 58 ---------------- docs/concepts/edge-infrastructure.md | 69 +++++++++++++++++++ docs/references/http-gateway-spec.md | 2 + 6 files changed, 71 insertions(+), 157 deletions(-) delete mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md delete mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md delete mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md delete mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md create mode 100644 docs/concepts/edge-infrastructure.md diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md deleted file mode 100644 index a3f4cc6..0000000 --- a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -learn_hub_id: 34276431179412 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34276431179412-Asset-Certification" -learn_hub_title: "Asset Certification" -learn_hub_section: "ICP and the Internet" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# Asset Certification - -A user interacting with the Internet Computer needs to be able to confirm that the responses they receive are actually coming from the Internet Computer and have not been tampered with. Traditionally, on the Internet, this problem is solved using public-key cryptography. The server running the service has a secret key and uses that to sign all its responses. A user can then verify the signature on the response using the server’s public key. - -Just like a web server in Web2 maintains a public-key/secret-key pair, the Internet Computer blockchain as a whole maintains a public-key/secret-key pair. Additionally, each individual subnet in the Internet Computer also maintains its own public-key/secret-key pair. When a new subnet is formed, the NNS issues a certificate for the subnet which contains a signature of the subnet's public key with the Internet Computer's public key. When the subnet responds to a user's message, the response contains a certificate chain, which includes a signature on the response by the subnet's public key and the certificate issued by the NNS to the subnet. The user can verify the certificate chain using the Internet Computer's public key similar to verifying a certificate chain in Web2. - -Each blockchain node shares only a piece of its subnet secret key. As a result, each node is incapable of signing a message by itself. But if at least 2/3rd of the nodes of a subnet agree on a message, they together can combine their secret key pieces to sign the message. The signed message can be verified easily using the subnet's public key. If the verification succeeds, it means that at least 2/3rd of the blockchain nodes running the canister agreed to deliver that message. The technology used by the Internet Computer to generate and maintain the secret key shares, and sign messages using the secret key shares is called [chain-key cryptography](https://internetcomputer.org/how-it-works/chain-key-technology/). - -The Internet Computer supports two types of messages: Query calls and Update calls. Query calls are similar to HTTP `GET` requests and do not modify the state of the Internet Computer. The query calls do not go through the consensus protocol. The user can make a query call to any blockchain node in the subnet, and only that (possibly malicious) blockchain node answers the query. As generating a certificate requires consensus from at least 2/3rd of the nodes of the subnet, the Internet Computer doesn't issue a certificate when responding to query calls. - -For efficiency reasons, the canisters deliver web pages to the client via query calls. However, as the client needs to verify the received content, the Internet Computer introduces the notion of [Certified Variables](https://internetcomputer.org/how-it-works/response-certification/). In a nutshell, a canister can a-priori choose to create a certificate for a piece of data and store it in the replicated state. Any user can later access the data along with its certificate via query calls. - -We can use the notion of the certified variables to certify all the assets (HTML, CSS, Javascript files, images, videos, etc.) of an app a-priori. There are 2 ways of performing the asset certification. 1) The canister developer can explicitly write code to manage and certify all the assets. 2) The canister developer can create an "asset canister", by creating a canister with type set to "asset" and specifying the folder containing all the assets. The asset canister is a regular canister, except that the boilerplate code for managing and certifying all the assets is taken care of for us. - -When a canister issues a response along with its certificate, a [HTTP Gateway](https://internetcomputer.org/how-it-works/smart-contracts-serve-the-web) can be used to verify the certificate before passing on the response to the client. - -For more information on certification, check [Certified Variables](https://internetcomputer.org/how-it-works/response-certification/). - diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md deleted file mode 100644 index e3b097c..0000000 --- a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -learn_hub_id: 34211943471892 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34211943471892-HTTP-Gateway-Protocol" -learn_hub_title: "HTTP Gateway Protocol" -learn_hub_section: "ICP and the Internet" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# HTTP Gateway Protocol - -The [HTTP Gateway Protocol](https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec) translates HTTP requests coming from a client (e.g., your browser) into API canister calls and then the responses back into HTTP responses. - -In the following, we describe the life of an HTTP request to a canister until it is turned into the corresponding HTTP response. This involves four components: - - 1. The client, which makes the HTTP request (e.g., a browser); - 2. An HTTP gateway, which translates the HTTP request into an API canister call and the resulting response into an HTTP response; - 3. An API boundary node, which routes the API canister call to a replica of the subnet hosting the target canister; - 4. A canister, which implements the HTTP interface. - - - -![](https://learn.internetcomputer.org/hc/article_attachments/34717980895636) - -_HTTP Gateway converts the format of HTTP Requests to canister API calls, and the resulting responses back to HTTP responses._ - -_ -_So let’s look at what happens when one opens a website that is hosted in a canister, e.g.,[ www.internetcomputer.org](https://internetcomputer.org/). - -It all starts in the browser. The browser does not know that this site is hosted on the Internet Computer and makes a normal HTTP request, just as it would for any other site. It sends that request to the server hosting internetcomputer.org, which is running the HTTP gateway protocol. - -This server takes the HTTP request and translates it into an API canister call. In particular, it turns the HTTP request into a query call to the http_request-method of the target canister and puts the requested path, the HTTP request headers and the body into the payload of that query call. How this works in detail is explained in the[ HTTP gateway protocol specification](https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec). Today, there exists one main implementation of the HTTP gateway protocol: the ic-http-gateway library, which is, for example, used in the HTTP gateways. - -The API boundary node simply takes the API canister call and forwards it to a replica node, which is part of the subnet that hosts the target canister. - -The canister receives that query call for its http_request-method, processes it and replies. To this end, the canister needs to implement the[ Canister HTTP Interface](https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec#canister-http-interface), which is part of the HTTP gateway protocol. - -The HTTP gateway receives the response from the canister and translates it back to an HTTP response. It unpacks the response, takes the status code, the supplied headers, the body, etc. and constructs an HTTP response from that. In addition to constructing the response, the HTTP gateway also verifies that the response is correct and has not been tampered with by a malicious replica node. To this end, each response comes with a certificate from the entire subnet (for more details check[ asset certification](https://learn.internetcomputer.org/hc/en-us/articles/34276431179412)). - -Finally, the browser receives the HTTP response and displays the site. - -## **Additional information** - -[Ic-http-gateway Library](https://github.com/dfinity/http-gateway/tree/main/packages/ic-http-gateway) - -[Response-verification](https://github.com/dfinity/response-verification): a collection of libraries to help canister developers with certifying their responses to work with the HTTP gateway protocol - diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md deleted file mode 100644 index c01e5ad..0000000 --- a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -learn_hub_id: 34574399808788 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34574399808788-ICP-and-the-Internet" -learn_hub_title: "ICP and the Internet" -learn_hub_section: "ICP and the Internet" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# ICP and the Internet - -The Internet Computer aims to extend the functionality of the internet beyond simply connecting devices and networks, but running applications in a tamper-proof manner. The first articles in this section, describe how users' requests and the Internet Computer's responses are transferred and verified - - * [Edge infrastructure:](https://learn.internetcomputer.org/hc/en-us/articles/34212818609684) how request and responses reach their destination, including caching and load-balancing - * [HTTP Gateway Protocol:](https://learn.internetcomputer.org/hc/en-us/articles/34211943471892) how HTTPs is translated into the Internet Computer Protocol - * [Asset certification:](https://learn.internetcomputer.org/hc/en-us/articles/34276431179412) how responses from the Internet Computer are verified - - - -The second part of this section explains how canisters can communicate with web2 servers and use their data for computations without trusted intermediaries. - - * [HTTPS outcalls:](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492) how canisters can interact with web2 - - - diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md deleted file mode 100644 index 036ca09..0000000 --- a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -learn_hub_id: 34212818609684 -learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34212818609684-ICP-Edge-Infrastructure" -learn_hub_title: "ICP Edge Infrastructure" -learn_hub_section: "ICP and the Internet" -learn_hub_category: "How does ICP work?" -migrated: false ---- - -# ICP Edge Infrastructure - -The edge infrastructure of the Internet Computer consists of two key components: API boundary nodes and HTTP gateways. These components work together to enable seamless communication between users and the Internet Computer while ensuring scalability, security, and efficient request processing. - -![](https://learn.internetcomputer.org/hc/article_attachments/34717950444948) - -**API Boundary Nodes:** API boundary nodes serve as the primary interface for interacting with the Internet Computer. They handle IC API requests—such as query and update calls—and efficiently route them to nodes (replica in the figure above) of the appropriate subnet. - -**HTTP Gateways:** HTTP gateways act as a translation layer between traditional HTTP and ICP communication, allowing direct browser access to canisters hosted on the Internet Computer. - - - -This split design provides flexibility for future expansions, enabling the integration of additional gateways that bridge between ICP and other established protocols such as DNS and SMTP. - -## API Boundary Nodes - -API boundary nodes are the globally distributed public interface of the Internet Computer. They receive requests from clients and efficiently route them to nodes of the appropriate subnet. This ensures seamless communication between IC-native applications and the decentralized network without reliance on centralized infrastructure. - -**Beyond Simple Routing** - -While their primary role is to deliver IC API requests (e.g., query and update calls), API boundary nodes perform several additional critical functions: - - * **Dynamic Routing** : Continuously monitor the Internet Computer core and adapt accordingly. - * **Load Balancing** : Distribute traffic efficiently to optimize performance. - * **Caching** : Store some responses temporarily to reduce latency and improve user experience. - * **Security Enforcement** : Implement safeguards to protect both themselves and the IC core from potential threats. - - - -**Fully Decentralized and NNS-Managed** - -API boundary nodes are an integral part of the Internet Computer, managed entirely by the [Network Nervous System (NNS)](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236). Any additions, removals, or upgrades require an NNS proposal, ensuring transparency and decentralization. These nodes operate on hardware owned by multiple independent node providers, similar to the replica nodes assigned to subnets. - -**Unified Deployment** - -API boundary nodes run a service called ic-boundary. The Internet Computer utilizes a single virtual machine (VM) image for both replica and API boundary nodes. The orchestrator component on each node determines the node’s role, launching either ic-replica (for replica nodes) or ic-boundary (for API boundary nodes). - -**Global Deployment** - -Currently, around 20 API boundary nodes are deployed worldwide, ensuring a resilient and performant network. An up-to-date list of the API boundary nodes is available on the [dashboard](https://dashboard.internetcomputer.org/nodes?s=100&type=ApiBoundary). - -## HTTP Gateways - -HTTP gateways add an extra layer to the Internet Computer, translating HTTP requests into IC API calls and forwarding them to the API boundary nodes. Thanks to these gateways, browsers and other HTTP-speaking clients can directly interact with canisters on the Internet Computer. This is why, for example, you can access the Internet Computer website, [internetcomputer.org](http://internetcomputer.org/), from a browser without the need for any additional software, even though the site is fully hosted onchain. - -The translation of HTTP to IC API calls and back is defined in the [HTTP Gateway Protocol](https://learn.internetcomputer.org/hc/en-us/articles/34211943471892). - -Since HTTP gateways act as a translation layer, they are not part of ICP and can be deployed and operated by anyone. This open model encourages a diverse set of gateways, enhancing redundancy and availability. - diff --git a/docs/concepts/edge-infrastructure.md b/docs/concepts/edge-infrastructure.md new file mode 100644 index 0000000..6a8a334 --- /dev/null +++ b/docs/concepts/edge-infrastructure.md @@ -0,0 +1,69 @@ +--- +title: "Edge Infrastructure" +description: "How requests reach ICP canisters: API boundary nodes, HTTP gateways, the HTTP Gateway Protocol, and asset certification." +--- + +The Internet Computer extends the internet beyond connecting devices and networks: it runs applications in a tamperproof manner. For a browser or an API client to interact with a canister, requests must travel through the ICP edge infrastructure, which translates standard HTTP into ICP's canister call protocol, routes calls to the right subnet, and certifies responses before they reach the client. + +The edge infrastructure has two main components: + +- **API boundary nodes** handle IC API requests (query and update calls) and route them to the correct subnet. +- **HTTP gateways** translate standard HTTP requests from browsers and other clients into IC API calls and translate responses back into HTTP. + +## API boundary nodes + +API boundary nodes are the globally distributed public interface of the Internet Computer. They receive IC API requests and route them to nodes on the appropriate subnet, providing seamless access to canisters without relying on centralized infrastructure. + +Beyond routing, API boundary nodes perform several additional functions: + +- **Dynamic routing.** They continuously monitor the network topology and adapt routing accordingly as subnets are added, removed, or reconfigured. +- **Load balancing.** Traffic is distributed across replica nodes to optimize performance. +- **Caching.** Some query responses are cached to reduce latency for frequently accessed data. +- **Security enforcement.** API boundary nodes implement safeguards that protect both themselves and the core protocol from abuse. + +API boundary nodes are an integral part of the network, governed by the NNS. Any addition, removal, or upgrade of API boundary nodes requires an NNS proposal, ensuring transparency. They run on hardware owned by independent node providers, similar to replica nodes. + +All API boundary nodes run a service called `ic-boundary`. The network uses a single VM image for both replica and API boundary nodes: the orchestrator component on each node determines its role by launching either `ic-replica` or `ic-boundary`. + +## HTTP gateways + +HTTP gateways translate standard HTTP requests into IC API calls and forward them to API boundary nodes. Because of this translation layer, browsers and other HTTP clients can access canisters directly without installing any special software. For example, a website fully hosted on ICP is accessible in any browser through a normal HTTPS URL. + +The HTTP Gateway Protocol (defined in the [HTTP Gateway Protocol Specification](../references/http-gateway-spec.md)) specifies exactly how this translation works. HTTP gateways are not part of ICP itself and can be operated by anyone. This open model encourages a diverse set of gateways, enhancing redundancy and availability. + +## HTTP Gateway Protocol + +When a browser opens a URL hosted by a canister, the following happens: + +1. The browser makes a normal HTTPS request to the domain (for example, `https://.icp0.io`). It has no awareness that the site runs on ICP. +2. The HTTP gateway receives the request and translates it into a query call to the canister's `http_request` method, placing the path, headers, and body into the call payload. +3. An API boundary node receives the IC API call and forwards it to a replica on the subnet that hosts the target canister. +4. The canister executes the `http_request` query, constructs an HTTP response (status, headers, body), and returns it. +5. The HTTP gateway receives the canister's response, verifies the certificate (see Asset certification below), and constructs a standard HTTP response. +6. The browser receives the HTTP response and renders the page. + +Canisters that serve HTTP must implement the Canister HTTP Interface defined in the HTTP Gateway Protocol Specification. The main implementation of the protocol is the [ic-http-gateway library](https://github.com/dfinity/http-gateway/tree/main/packages/ic-http-gateway). + +## Asset certification + +When a canister responds to a query call via the HTTP gateway, a single replica node handles the request. The client cannot rely solely on that node's response, since a compromised node could return tampered content. + +ICP solves this through **asset certification**: a mechanism for canisters to prove in advance that a response is genuine. It works as follows: + +- The ICP network maintains a public key at the network level. Each subnet also has its own public key, which is certified by the NNS using the network key. +- When a subnet responds to a message, the response includes a certificate chain: the subnet's signature on the response and the NNS certificate on the subnet's key. Any client can verify this chain using only the ICP network's public key. +- Because generating a subnet certificate requires agreement from at least two thirds of the subnet's nodes (using [chain-key cryptography](chain-key-cryptography.md)), a certified response represents network-level consensus, not a single node's assertion. +- Query calls do not go through consensus and are not automatically certified. To serve certified query responses, canisters use **certified variables**: the canister stores a certificate for a piece of data in the replicated state during an update call. Any user can later retrieve both the data and its certificate via a query call and verify the certificate independently. +- For web assets (HTML, CSS, JavaScript, images), canisters can certify all assets upfront. The asset canister provided by DFINITY handles this automatically: developers specify a folder of assets and the asset canister manages and certifies them. + +When the HTTP gateway receives a canister response that includes a certificate, it verifies the certificate before passing the response to the client. This is what makes ICP-hosted web content verifiable end-to-end without trusting any single node. + +For practical guidance on certifying canister responses, see [Certified variables](../guides/backends/certified-variables.md). + +## Further reading + +- [HTTP Gateway Protocol Specification](../references/http-gateway-spec.md) — detailed protocol definition +- [Certified variables guide](../guides/backends/certified-variables.md) — how to certify canister responses +- [Chain-key cryptography](chain-key-cryptography.md) — the signature mechanism underlying certification + + diff --git a/docs/references/http-gateway-spec.md b/docs/references/http-gateway-spec.md index c67fe9f..4e89f8c 100644 --- a/docs/references/http-gateway-spec.md +++ b/docs/references/http-gateway-spec.md @@ -5,6 +5,8 @@ sidebar: order: 12 --- +See also: [Edge Infrastructure](../concepts/edge-infrastructure.md) — conceptual overview of API boundary nodes, HTTP gateways, and asset certification. + ## Introduction The HTTP Gateway Protocol is an extension of the Internet Computer Protocol that allows conventional HTTP clients to interact with the Internet Computer network. This is important for software such as web browsers to be able to fetch and render client-side canister code, including HTML, CSS, and JavaScript as well as other static assets such as images or videos. The HTTP Gateway does this by translating between standard HTTP requests and [API canister calls](./ic-interface-spec/https-interface.md#http-interface) that the Internet Computer Protocol will understand. From 1a86481322b37f0b4fb6bcf5562c8088b27160a3 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 6 May 2026 18:39:01 +0200 Subject: [PATCH 2/2] fix: replace em-dashes and add section anchor in edge-infrastructure docs --- docs/concepts/edge-infrastructure.md | 8 ++++---- docs/references/http-gateway-spec.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/concepts/edge-infrastructure.md b/docs/concepts/edge-infrastructure.md index 6a8a334..58ee1db 100644 --- a/docs/concepts/edge-infrastructure.md +++ b/docs/concepts/edge-infrastructure.md @@ -52,7 +52,7 @@ ICP solves this through **asset certification**: a mechanism for canisters to pr - The ICP network maintains a public key at the network level. Each subnet also has its own public key, which is certified by the NNS using the network key. - When a subnet responds to a message, the response includes a certificate chain: the subnet's signature on the response and the NNS certificate on the subnet's key. Any client can verify this chain using only the ICP network's public key. -- Because generating a subnet certificate requires agreement from at least two thirds of the subnet's nodes (using [chain-key cryptography](chain-key-cryptography.md)), a certified response represents network-level consensus, not a single node's assertion. +- Because generating a subnet certificate requires agreement from at least two thirds of the subnet's nodes (using [chain-key cryptography](chain-key-cryptography.md#threshold-bls-signatures)), a certified response represents network-level consensus, not a single node's assertion. - Query calls do not go through consensus and are not automatically certified. To serve certified query responses, canisters use **certified variables**: the canister stores a certificate for a piece of data in the replicated state during an update call. Any user can later retrieve both the data and its certificate via a query call and verify the certificate independently. - For web assets (HTML, CSS, JavaScript, images), canisters can certify all assets upfront. The asset canister provided by DFINITY handles this automatically: developers specify a folder of assets and the asset canister manages and certifies them. @@ -62,8 +62,8 @@ For practical guidance on certifying canister responses, see [Certified variable ## Further reading -- [HTTP Gateway Protocol Specification](../references/http-gateway-spec.md) — detailed protocol definition -- [Certified variables guide](../guides/backends/certified-variables.md) — how to certify canister responses -- [Chain-key cryptography](chain-key-cryptography.md) — the signature mechanism underlying certification +- [HTTP Gateway Protocol Specification](../references/http-gateway-spec.md): detailed protocol definition +- [Certified variables guide](../guides/backends/certified-variables.md): how to certify canister responses +- [Chain-key cryptography](chain-key-cryptography.md): the signature mechanism underlying certification diff --git a/docs/references/http-gateway-spec.md b/docs/references/http-gateway-spec.md index 4e89f8c..ef26c53 100644 --- a/docs/references/http-gateway-spec.md +++ b/docs/references/http-gateway-spec.md @@ -5,7 +5,7 @@ sidebar: order: 12 --- -See also: [Edge Infrastructure](../concepts/edge-infrastructure.md) — conceptual overview of API boundary nodes, HTTP gateways, and asset certification. +See also: [Edge Infrastructure](../concepts/edge-infrastructure.md): conceptual overview of API boundary nodes, HTTP gateways, and asset certification. ## Introduction