Skip to content

Commit fd1d221

Browse files
committed
fix(concepts): rewrite https-outcalls intro and add non-replicated mode
- Remove "blockchain", "smart contract", and "offchain/onchain" jargon; reframe for traditional cloud developers using replicated systems terminology - Combine the redundant intro and "Why HTTPS outcalls exist" section into a single lean intro covering what, why, and the oracle alternative - Add "Replicated and non-replicated mode" section documenting the shipped is_replicated=false capability — previously absent from the concept page - Remove "Flexible quorum" from Future extensions (already shipped as is_replicated=false); keep "Multiple responses" which is genuinely future - Update frontmatter description to be capability-first for cloud developers
1 parent 724aca2 commit fd1d221

1 file changed

Lines changed: 9 additions & 8 deletions

File tree

docs/concepts/https-outcalls.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,21 @@
11
---
22
title: "HTTPS Outcalls"
3-
description: "How canisters make HTTP requests to external services with consensus on responses"
3+
description: "How canisters call external APIs and web services directly, without oracles or intermediaries."
44
sidebar:
55
order: 8
66
---
77

8-
Canisters on the Internet Computer can make HTTP requests to any public web server (fetching API data, posting to webhooks, or querying offchain services) without relying on oracles or other intermediaries. This capability is called **HTTPS outcalls**.
8+
Canisters on the Internet Computer can make HTTP requests to any public web server fetching API data, posting to webhooks, or querying external services without relying on oracles or other intermediaries. This capability is called **HTTPS outcalls**.
99

10-
What makes this unusual for a blockchain is that every replica in a subnet executes the same code independently. When a canister makes an HTTPS outcall, all replicas in the subnet send the same request to the external server, each receives its own response, and the subnet must reach consensus on a single response to return to the canister. This mechanism preserves the replicated state machine guarantees that make canisters trustworthy while enabling direct communication with the conventional web.
10+
ICP runs every canister on a subnet where all replicas execute the same code independently and must reach consensus. Outbound HTTP requests are non-trivial in this model: each replica independently contacts the server and typically receives a slightly different response — timestamps, headers, or field ordering vary — which would cause replicas to diverge. The traditional workaround is **oracles**: third-party services that fetch external data and relay it to the network, at the cost of extra complexity, fees, and a trust assumption. HTTPS outcalls solve the problem directly: the subnet reaches consensus over the response internally, so canisters call external APIs without a middleman.
1111

12-
## Why HTTPS outcalls exist
12+
## Replicated and non-replicated mode
1313

14-
Traditional blockchains cannot make outbound HTTP requests. Smart contracts are deterministic state machines: if different nodes received different responses from an external server, their state would diverge and consensus would break. The standard workaround is **oracles**: trusted third-party services that fetch offchain data and submit it onchain.
14+
HTTPS outcalls have two modes controlled by the `is_replicated` field:
1515

16-
Oracles work, but they add complexity, cost, and trust assumptions. You must choose an oracle provider, pay their fees, and trust that they relay data honestly. With HTTPS outcalls, canisters call external APIs directly. The IC protocol handles the consensus problem internally, so you get the same result (reliable offchain data onchain) without the middleman.
16+
**Replicated mode** (default) is what the consensus mechanism below describes: all replicas independently fetch the URL, a transform function normalizes the responses, and the subnet agrees on a single result. This provides the strongest integrity guarantee — the response is confirmed by a supermajority of nodes, making it extremely difficult for any single party to tamper with it. The tradeoff is that all replicas (typically 13) send the same request to the external server within milliseconds of each other, which can trigger API rate limits.
17+
18+
**Non-replicated mode** (`is_replicated = false`) has a single replica make the request. No consensus is needed, so there is no transform function requirement and no rate-limit pressure on the external server. The tradeoff is trust: the single replica that handles the request could theoretically observe or modify the response before returning it to the canister. This mode is appropriate when the endpoint is idempotent, rate limits are a concern, or you're making POST requests where duplicate submissions would cause problems.
1719

1820
## How outcalls reach consensus
1921

@@ -100,9 +102,8 @@ HTTPS outcalls can replace oracles for most use cases: price feeds, API queries,
100102

101103
## Future extensions
102104

103-
Two extensions are under consideration that may affect architecture decisions:
105+
One extension is under consideration that may affect architecture decisions:
104106

105-
- **Flexible quorum:** A canister could specify that only a single replica (instead of all replicas) makes the request. This would solve the idempotency problem for POST requests and reduce rate-limit pressure on external servers.
106107
- **Multiple responses:** Instead of consensus on a single response, the canister could receive all individual replica responses and resolve differences in application logic: useful for fast-moving data like price feeds.
107108

108109
## Next steps

0 commit comments

Comments
 (0)