Boundary Nodes

The boundary nodes are the gateway to the Internet Computer (IC), and 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 icp-api.io/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 a replica node on the correct subnet in the IC.

Filtering within the boundary node consists only of rate-limiting. The rate-limits are in place to protect the IC from being overwhelmed with external accesses.

After an API canister call passed the filtering stage, the boundary node 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

The HTTP endpoint is served through two main domains: ic0.app and icp0.io. In the following, we use for simplicity only ic0.app, even though both domains could be used equally.

Unfortunately, browsers don't 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 providing a mechanism to translate HTTP requests into API canister calls allowing a client to interact with canisters. A gateway 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 with icx-proxy one implementation of the HTTP gateway protocol, which runs directly on the boundary node and operates in two different modes:

Enforcing response verification under <canister_id>.ic0.app;

Permissive response verification under <canister_id>.raw.ic0.app.

However, before serving any HTTP request, the HTTP Gateway first passes the incoming request through a filter, which can be used to implement content filtering allowing operators to comply with local legal frameworks (e.g., blocking gambling services in a particular geography). To learn more about content filtering see Content Filtering via The Boundary Nodes.

Then, the requests are passed on to icx-proxy, which translates the HTTP requests into API canister calls. These API canister calls are passed onto the API endpoint of the boundary node, which forwards it to a replica in the IC.

Upon receiving the response, icx-proxy checks certificate of the response and constructs an HTTP response back to the client. In enforcing mode, icx-proxy only sends the response to the client if it is correctly certified and an error otherwise. In permissive mode, icx-proxy only checks the certificate if there is one. The permissive mode is mainly required for legacy canisters that do not implement response verification or for dynamic responses that cannot easily be certified.

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

The HTTP gateway on the boundary nodes 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 for HTTP assets. Responses to requests are cached for 10s.

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.