A proxy canister lets your engine's canisters use Internet Computer services they cannot reach on their own: signing Bitcoin and Ethereum transactions, deriving VetKeys, and any other call that must pay cycles across the network (for example, reading a live exchange rate). This article explains why that extra step exists and what a proxy does.
Your engine and its canisters
Your app runs on a cloud engine: a set of nodes running the Internet Computer protocol, dedicated to you. The engine runs on a single subnet (one cluster of those nodes). Each part of your app is a canister, a bundle of code with its own persistent state, and every node in the engine keeps an identical copy of it.
Some of the Internet Computer's most useful services are not part of your engine. They run on other subnets of the network, and each call to them costs cycles (the fuel that pays for computation on the Internet Computer).
Why your engine's canisters need a proxy
A canister on a cloud engine cannot attach cycles to a call that crosses to another subnet. The calls below all cross a subnet boundary and carry cycles, so your engine's canisters cannot make them directly: the call is rejected.
- Chain-key signatures. Sign Bitcoin and Ethereum transactions straight from a canister.
- VetKeys. Derive encryption keys on demand for private data.
- Any other call that needs cycles. More generally, any cross-subnet call your canister has to pay cycles for. For example, asking the exchange rate canister (XRC) for a live rate.
A proxy canister is how you make these calls anyway.
What a proxy does
A proxy is a small canister that lives on a regular application subnet (not on your engine) and holds a cycles balance you fund. When one of your engine's canisters needs a paid service, it makes a cheap, cycle-free call to the proxy. The proxy re-issues that call from where it sits, attaches the cycles, and relays the reply straight back.
Your canister gets the result, and the proxy covers the cost from its balance. You only need a proxy for these cross-subnet, paid calls. Ordinary calls inside your engine do not use it.
Deploy and fund a proxy
- Open your engine console and go to Applications, then Proxy canisters.
- Select Deploy a proxy and choose an initial balance (minimum $5). Optionally turn on automatic top-up to recharge from your saved card when the balance runs low.
- Copy the proxy canister id from the table. Your app calls this id.
Every canister on your engine is allowed to use the proxy, so there is nothing else to configure. You can top up or delete a proxy from the same table at any time.
Good to know
- Mind the balance. A proxy pays for its calls from the cycles balance you fund. If it runs low, its calls start failing until you top it up, so enable automatic top-up for the services you depend on. Each proxy has its own balance.
- One proxy processes calls one at a time. Like any canister, a proxy handles the calls routed through it serially, not in parallel. If many of your canisters lean on a single proxy at once, their calls queue behind each other. For higher throughput, deploy more than one proxy and point different canisters at different proxy ids.
- Keys are isolated per canister. When a proxy derives signing or encryption keys, each of your canisters gets its own separate keys: one canister can never sign or decrypt with another's. A key obtained through the proxy is not the same as one obtained by calling the network directly, so always request the key and use it through the same proxy.
Learn more