Skip to content

feat: adopt icp.net as the mainnet HTTP gateway domain (icp-cli v1.0.0)#226

Open
marc0olo wants to merge 4 commits into
mainfrom
chore/adopt-icp-net-gateway-domain-224
Open

feat: adopt icp.net as the mainnet HTTP gateway domain (icp-cli v1.0.0)#226
marc0olo wants to merge 4 commits into
mainfrom
chore/adopt-icp-net-gateway-domain-224

Conversation

@marc0olo

@marc0olo marc0olo commented Jun 17, 2026

Copy link
Copy Markdown
Member

Summary

Resolves #224. icp-cli v1.0.0 changed the default mainnet HTTP gateway from icp0.io to icp.net (browser canister access is now https://<canister-id>.icp.net and raw.icp.net). This reconciles the skills with the developer-docs change (mirror PR open there).

Changed → icp.net (gateway / browser canister-access URLs)

File What changed
asset-canister mainnet access-URL table, certified/raw serving domains, browser-open URL; plus the Node.js HttpAgent host changed from the legacy ic0.app access domain to the canonical API endpoint icp-api.io (the rest of the corpus already uses icp-api.io as the agent host)
custom-domains default access URL, .well-known/ic-domains fetch URLs, and the custom-domains/v1 REST API host (issue confirms it resolves on icp.net)
certified-variables mainnet curl example
deploy-to-cloud-engine frontend canister access URL
internet-identity illustrative frontend_origins / TRUSTED_ORIGIN examples

custom-domains HttpAgent host guidance

Pitfall 8 and the HttpAgent Configuration section are corrected: a recent @icp-sdk/core HttpAgent resolves an omitted host to https://icp-api.io on a custom domain, so you do not need to set it. The guidance now warns against the real mistake — pointing host at your custom domain / window.location.origin, which is the gateway and does not serve /api/v2. Scoped to the mainnet custom-domains service only.

Kept (NOT the gateway)

  • API / agent hosts stay icp-api.ioicp.net is gateway-only.
  • Named dapp domains (nns.ic0.app) in icp-cli and agent-web-identity.
  • II delegation rewriting pitfall (internet-identity): II still rewrites icp0.ioic0.app at the protocol level (per the II spec — unchanged by the gateway rename), so this behavioral claim is left as-is rather than turned into a meaningless "icp.net vs icp.net" statement. This is the caveat the issue flagged.
  • icp-cli and agent-web-identity SKILL.md needed no changes (only API host + named dapp domains).

Evals

  • Updated custom-domains API-endpoint assertions and the asset-canister mainnet-host behavior to match the domain change.
  • Updated the custom-domains "HttpAgent host configuration" case to match the corrected host guidance.
  • Added an asset-canister regression guard: the mainnet browser URL must be <id>.icp.net (not ic0.app/icp0.io/icp-api.io).
  • The internet-identity rewriting eval is intentionally left referencing icp0.io/ic0.app since the pitfall it tests is unchanged.
Eval results (new/changed cases)
asset-canister — "Mainnet browser-access domain is icp.net": WITH 3/3
  ✅ Gives the URL as https://<canister-id>.icp.net
  ✅ Does NOT use the legacy ic0.app or icp0.io gateway domains
  ✅ Does NOT use icp-api.io (that is the API endpoint, not the browser gateway)

custom-domains — "Domain registration API": WITH 4/4
  ✅ Uses the validate endpoint: GET https://icp.net/custom-domains/v1/app.example.com/validate
  ✅ Uses the registration endpoint: POST https://icp.net/custom-domains/v1/app.example.com
  ✅ Uses the status check endpoint: GET https://icp.net/custom-domains/v1/app.example.com
  ✅ Does NOT invent non-existent API endpoints or parameters

custom-domains — "HttpAgent host configuration": WITH 3/3
  ✅ Identifies that the custom domain serves only the HTTP gateway, not the /api/v2 API endpoint, so host must not point at it
  ✅ Says to leave host unset (defaults to https://icp-api.io on a custom domain) or set it explicitly to https://icp-api.io
  ✅ Does NOT recommend setting host to the custom domain or window.location.origin

npm run validate → all 26 skills pass.

Closes #224

icp-cli v1.0.0 changed the default mainnet HTTP gateway from icp0.io to
icp.net (browser canister access is now <id>.icp.net / raw.icp.net).
Reconcile the skills with the developer-docs change.

Changed (gateway / browser canister-access URLs):
- asset-canister: mainnet access URL, certified/raw serving domains,
  browser-open URL; also fix the Node.js HttpAgent host from the legacy
  ic0.app access domain to the canonical API endpoint icp-api.io
- custom-domains: default access URL, ic-domains fetch URLs, and the
  custom-domains/v1 REST API host (confirmed to resolve on icp.net)
- certified-variables: mainnet curl example
- deploy-to-cloud-engine: frontend canister access URL
- internet-identity: illustrative frontend_origins / TRUSTED_ORIGIN

Kept (NOT the gateway):
- API/agent hosts stay icp-api.io (icp.net is gateway-only)
- Named dapp domains (nns.ic0.app) in icp-cli and agent-web-identity
- II delegation rewriting pitfall: II still rewrites icp0.io -> ic0.app
  at the protocol level (per the II spec, unchanged by the gateway
  rename), so that behavioral claim stays as-is rather than becoming a
  meaningless icp.net-vs-icp.net statement

Evals: updated custom-domains API-endpoint and asset-canister host
assertions; added an asset-canister guard that the mainnet browser URL
is <id>.icp.net (not ic0.app/icp0.io/icp-api.io). Both new/updated
cases pass with the skill.

Closes #224
@marc0olo marc0olo requested review from a team and JoshDFN as code owners June 17, 2026 20:15
@github-actions

github-actions Bot commented Jun 17, 2026

Copy link
Copy Markdown

Skill Validation Report

Project Checks


WARNINGS (1):
  ⚠ certified-variables/SKILL.md: missing evaluations/certified-variables.json — see CONTRIBUTING.md for evaluation guidance

✓ Project checks passed for 5 skills (1 warnings)

Comment thread skills/custom-domains/SKILL.md Outdated
marc0olo added 3 commits June 18, 2026 09:34
The pitfall and HttpAgent Configuration section claimed the agent
"cannot auto-detect the IC API host on custom domains, so you must set
host explicitly." That is inaccurate for recent agents. Per
@icp-sdk/core determineHost(), an omitted host defaults to the local
replica for localhost/127.0.0.1 origins and to https://icp-api.io for
every other origin — including custom domains and icp.net. So on a
custom domain you do not need to set host; it already resolves to the
mainnet API boundary nodes.

Reframe the pitfall around the real mistake: pointing host at the custom
domain (or window.location.origin), which serves only the HTTP gateway,
not /api/v2, so calls fail. Update the eval case to match.
Rewrite the HttpAgent Configuration section with an explicit
resolution table (what an omitted host resolves to per runtime) and a
per-scenario "what to do" list covering all cases:

- mainnet browser frontend (icp.net / custom domain / legacy gateways):
  leave host unset → resolves to icp-api.io
- mainnet Node.js: unset or icp-api.io
- local dev in the browser on *.localhost: unset (auto-detects replica)
- local dev in Node.js: MUST set host to the local replica URL — no
  window.location to detect localhost, so omitted host hits mainnet
- non-mainnet/custom network: MUST set host to that network's API
  endpoint — the icp-api.io default points at mainnet

Clarify that host is the API endpoint, never the gateway domain the
frontend is served from. Tighten pitfall 8 to point at the section.

Add an eval for the Node.js-local case (omitted host silently hits
mainnet), the most counterintuitive of the must-set-host scenarios.
The custom-domains skill covers only the mainnet IC custom-domains
service — you cannot have a custom domain on a local replica or a custom
network. Drop the local-development and custom-network HttpAgent cases
(and the resolution table) added in the previous commit; they were
out of scope and diluted the skill.

The section now states only what is relevant: a mainnet frontend served
from a custom domain does not need host set (it resolves to icp-api.io),
and must never point host at the gateway/custom domain. Remove the
matching out-of-scope Node.js-local eval case.
@marc0olo marc0olo requested a review from raymondk June 18, 2026 10:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt icp.net as the mainnet HTTP gateway domain (icp-cli v1.0.0)

2 participants