Boundary Nodes
The boundary nodes are the gateway to the Internet Computer (IC), which allow users to seamlessly access the canister smart contracts running on it. The following figure shows how the boundary nodes form the edge of the IC and all accesses to the IC have to go through one of the boundary nodes.
Boundary Node Internals
At a closer look, boundary nodes consist of two parts: the API node, which provides an endpoint for API canister calls, and the HTTP gateway, which provides an HTTP endpoint for users to access the canisters hosted on the IC with their stock browser.
API Node
The API endpoint resides at ic0.app/api/v2 and is specified in the IC’s Interface Specification.
Whenever a boundary node receives an API canister call, it passes it through a filter and then routes it to the right replica node in the IC.
Filtering within the boundary node consists of rate-limiting and an operator-maintained denylist. The rate-limits are in place to protect the IC from being overwhelmed with external accesses. The denylist allows a boundary node operator to comply with local legal frameworks (e.g., blocking gambling services in a particular geography).
After an API canister call passed the filtering stage, the boundary node extracts infers the destination canister ID and uses the routing table to look up the subnet in which this canister is hosted. It then randomly chooses a replica within that subnet to which it forwards the API call. The random selection of the target replica ensures that an API call eventually reaches an honest node when the client keeps retrying.
Finally, the boundary node forwards the API canister call to the selected replica node in the core of the IC.
Since the API Node is simply passing the API canister call on to the IC, no trust is required.
HTTP Gateway
Unfortunately, not all applications natively support API canister calls and therefore cannot directly talk to the canisters hosted on the IC. The HTTP gateway protocol bridges that gap by enabling canisters to handle conventional HTTP requests allowing, for example, browsers to interact with canisters. A gateway implementing this protocol translates between HTTP requests and API canister calls and can be implemented in various forms (e.g., as a stand-alone proxy, as a browser plugin, or as a service worker).
The boundary nodes provide two different implementations of the HTTP gateway protocol:
- Service worker: under
<canister_id>.ic0.app, the boundary nodes serve a service worker, which is installed in the browser and acts as an HTTP gateway directly in the user’s browser;
icx-proxy: under<canister_id>.raw.ic0.app, the boundary node runsicx-proxy, an HTTP gateway implementation suitable for all clients that do not support a service worker.
Service Worker
When accessing <canister_id>.ic0.app, the boundary node returns a service worker implementing the HTTP gateway protocol, which is installed directly in the user’s browser (step 1 and 2). From then on, the service worker will intercept all HTTP requests and translate them to API canister calls (step 3). These API canister calls will then go through the API endpoint of the boundary node to the IC (step 4). The replica sends the response back through the boundary node to the service worker (step 5 and 6). For all responses, the service worker verifies the correctness of the response and only translates it into a proper HTTP response for the browser if it passes all the checks (step 7).
icx-proxy
The HTTP Gateway endpoint implements the HTTP gateway protocol, which translates between HTTP requests and API canister calls. This endpoint resides at <canister_id>.raw.ic0.app. Whenever a boundary node receives such a request, it forwards it to icx-proxy, a service running directly on the boundary node that implements the HTTP gateway protocol. icx-proxy translates the HTTP requests into API canister calls and forwards them to the API endpoint of the boundary node. It verifies the certificates of the responses and constructs an HTTP response to send back to the client. Here, the user needs to trust the boundary node as the boundary node is constructing the API calls and verifying the correctness of the IC’s response.
Additional Features of the Boundary Nodes
Globally-Distributed
The boundary nodes serving ic0.app are globally distributed and organized in regional pools. All requests are directed to the geographically closest pool and load balanced over the instances within that pool. The health of the boundary nodes is constantly monitored and in case of failure, boundary nodes will be removed from the pools.
SEO
Bots and crawlers, such as the ones used by search engines, unfortunately do not support service workers and are therefore not able to index content hosted under ic0.app out-of-the-box. However, they are able to access all the content under raw.ic0.app as the translation from HTTP requests to API calls happens within the boundary node. Therefore, boundary nodes detect all accesses of crawlers and bots to ic0.app and internally redirect them to icx-proxy. This allows the dapps running on the Internet Computer to seamlessly integrate into the Web 2.0 world. These dapps can be indexed by search engines and their metadata can be read in order to generate previews and cards on social platforms.
Caching
To improve the user-perceived performance of the dapps hosted on the IC, the boundary nodes currently provide response caching. Responses to requests are cached for 1s.
Future Boundary Node Developments
To follow future boundary node developments check out the public roadmap, the IC developer forum and the thread on the future boundary node architecture.