feat: allow HTTP requests with effective subnet ID by mraszyk · Pull Request #6224 · dfinity/portal

mraszyk · 2026-04-15T08:08:12Z

This PR enables update calls (to create a canister by subnet admins) and query calls (to list all canisters on a subnet by subnet admins) to be submitted to URLs with the (effective) subnet ID on which the canister is created or whose canisters should be enumerated (instead of a dummy canister ID from the canister ranges of the subnet according to the routing table). This streamlines the developer experience.

New endpoints:

/api/v4/subnet/<effective_subnet_id>/call;
/api/v3/subnet/<effective_subnet_id>/query.

Modified (existing) endpoints:

/api/v3/subnet/<effective_subnet_id>/read_state.

Copilot

Pull request overview

This PR updates the IC HTTPS interface specification to allow submitting update calls using an effective subnet ID in the URL (in addition to effective canister IDs), primarily to support create_canister submissions by subnet admins.

Changes:

Document new /api/v2/subnet/<effective_subnet_id>/call and /api/v4/subnet/<effective_subnet_id>/call endpoints alongside existing canister call endpoints.
Add a new “Effective subnet id” section and corresponding formalization (is_effective_subnet_id).
Extend the formal state-transition and read_state access-control rules to cover subnet-call submission and request-status polling.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

This PR adds a new public HTTP endpoint `/api/v4/subnet/<effective_subnet_id>/call` on the replica that supports call to the `create_canister` endpoint of the management canister (`aaaaa-aa`). It is specified in this [PR](dfinity/portal#6224). --------- Co-authored-by: IDX GitHub Automation <infra+github-automation@dfinity.org>

…RL (dfinity#9977) This PR adds a new public HTTP endpoint `/api/v3/subnet/<effective_subnet_id>/query` on the replica that supports call to the `list_canisters` endpoint of the management canister (`aaaaa-aa`). It is specified in this [PR](dfinity/portal#6224). Note. PocketIC support will be added in a separate PR. --------- Co-authored-by: Leo Eichhorn <99166915+eichhorl@users.noreply.github.com>

…dfinity#9982) This PR enables to retrieve the status of an (asynchronous) update call via the (existing) public HTTP endpoint `/api/v3/subnet/<effective_subnet_id>/read_state` on the replica. It is specified in this [PR](dfinity/portal#6224). In more detail, this PR is needed if the synchronous update call endpoint `/api/v4/subnet/.../call` returns 202 and thus the user needs to process the update call (to create canister as nothing else is allowed on `/api/v4/subnet/.../call`) asynchronously (by polling `/api/v3/subnet/.../read_state` for the `/request_status/...`). --------- Co-authored-by: IDX GitHub Automation <infra+github-automation@dfinity.org>

mraszyk · 2026-04-24T08:16:54Z

@r-birkner The replica implementation of this PR has been merged to master of dfinity/ic (but not yet fully rolled out).

…finity#10008) This PR adds PocketIC support for the new HTTP endpoints - `/api/v4/subnet/<effective_subnet_id>/call`; - `/api/v3/subnet/<effective_subnet_id>/query`; specified in this [PR](dfinity/portal#6224). Tests will be added once the new endpoints are supported in `ic-agent`.

Copilot

Pull request overview

Updates the IC interface specification to document and formally specify new subnet-scoped HTTPS endpoints that accept an effective subnet ID directly in the URL, improving the UX for subnet-admin canister creation and canister enumeration flows.

Changes:

Document /api/v4/subnet/<effective_subnet_id>/call as a restricted management-canister canister-creation endpoint.
Document /api/v3/subnet/<effective_subnet_id>/query as a restricted management-canister list_canisters endpoint.
Extend the formal spec and access-control rules around effective subnet IDs and subnet read_state request-status access.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Updates the IC HTTPS interface specification to allow subnet-admin operations to be addressed by effective subnet ID in the request URL (for canister creation and subnet canister enumeration), reducing the need for dummy canister IDs for routing.

Changes:

Document new endpoints /api/v4/subnet/<effective_subnet_id>/call and /api/v3/subnet/<effective_subnet_id>/query with restricted Management Canister usage.
Extend the read_state and certification/verification text to cover subnet-scoped requests and subnet query signature verification.
Add/extend formal rules for “effective subnet id” and subnet-scoped call submission and read_state access control.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

This PR updates the IC HTTPS interface specification to allow subnet-admin management calls to be routed via URLs containing an effective subnet ID (instead of using a dummy effective canister ID from routing-table ranges), improving ergonomics for canister creation and subnet canister enumeration.

Changes:

Document new endpoints /api/v4/subnet/<effective_subnet_id>/call and /api/v3/subnet/<effective_subnet_id>/query, and clarify their restricted scope (Management Canister only).
Extend certificate/verification and effective-id rules to cover subnet-scoped calls/queries and subnet-scoped read_state request-status polling.
Add a formal transition for submitting a subnet-scoped management call to /api/v4/subnet/<ESID>/call.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Updates the IC HTTPS interface specification to support submitting certain management-canister calls via URLs that use an effective subnet ID (instead of a “dummy” effective canister ID), aligning the documented API surface with the intended subnet-admin workflows.

Changes:

Document new endpoints /api/v4/subnet/<effective_subnet_id>/call (restricted canister-creation updates) and /api/v3/subnet/<effective_subnet_id>/query (restricted list_canisters query).
Extend the spec with “Effective subnet id” rules and update certificate verification predicates for subnet queries.
Add formal state/spec transitions and access-control rules related to subnet-scoped requests (including subnet_admins and request submission semantics).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

This PR updates the IC HTTPS interface specification to allow submitting restricted management-canister operations via subnet-scoped URLs that carry an effective subnet ID, improving the admin/developer workflow for canister creation and subnet canister enumeration.

Changes:

Document new subnet-scoped endpoints: /api/v4/subnet/<effective_subnet_id>/call and /api/v3/subnet/<effective_subnet_id>/query.
Extend/update spec text and formal predicates to define “effective subnet id” handling and corresponding certificate verification logic.
Update the abstract state model/spec transitions to incorporate subnet-admin authorization for these subnet-scoped operations.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

feat: allow HTTP requests with effective subnet ID

cce8487

github-actions Bot added the interface-spec Changes to the IC Interface Specification label Apr 15, 2026

mraszyk requested a review from Copilot April 15, 2026 08:12

Copilot started reviewing on behalf of mraszyk April 15, 2026 08:13 View session

Copilot AI reviewed Apr 15, 2026

View reviewed changes

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md

Comment thread docs/references/ic-interface-spec.md Outdated

mraszyk and others added 7 commits April 15, 2026 10:30

Point out that subnet ID cannot be used for every update call

19be05d

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Point out that subnet ID cannot be used for every update call

d045c9d

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Point out that subnet ID cannot be used for every update call

c662b0f

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Point out that subnet ID cannot be used for every update call

86dc663

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

manual fixes

0a448a7

no api/v2/subnet/.../call

64933c3

fix

8bd78e0

mraszyk mentioned this pull request Apr 17, 2026

feat: enable canister creation with subnet ID in the URL dfinity/ic#9919

Merged

mraszyk added 2 commits April 20, 2026 09:48

fixes

1347882

query call to ic00.list_canisters

ca8f9b5

This was referenced Apr 22, 2026

feat: enable listing canisters via query call with subnet ID in the URL dfinity/ic#9977

Merged

feat: enable asynchronous canister creation with subnet ID in the URL dfinity/ic#9982

Merged

mraszyk mentioned this pull request Apr 24, 2026

feat(PocketIC): support update/query calls with subnet ID in the URL dfinity/ic#10008

Merged

mraszyk added 2 commits April 27, 2026 10:41

Merge branch 'master' into mraszyk/effective-subnet-id

559b6a8

provisional_create_canister_with_cycles

292d156

mraszyk requested a review from Copilot April 28, 2026 08:51

Copilot started reviewing on behalf of mraszyk April 28, 2026 08:51 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md Outdated

mraszyk and others added 2 commits April 28, 2026 11:06

Potential fix for pull request finding

973c3e8

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

fix: no @dfinity/research in CODEOWNERS (#6233)

1348e2d

Copilot AI reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md

mraszyk added 2 commits April 28, 2026 11:31

typos

03a0d46

assert SubnetId matches effective_subnet_id

bccc3d2

mraszyk requested a review from Copilot April 28, 2026 09:33

Copilot started reviewing on behalf of mraszyk April 28, 2026 09:36 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md

mraszyk added 2 commits April 28, 2026 11:54

fixes

b19d81f

verify_subnet_response

8358aee

mraszyk requested a review from Copilot April 28, 2026 10:01

Copilot started reviewing on behalf of mraszyk April 28, 2026 10:02 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md Outdated

Comment thread docs/references/ic-interface-spec.md Outdated

fixes

f41dee3

mraszyk requested a review from Copilot April 28, 2026 10:17

Copilot started reviewing on behalf of mraszyk April 28, 2026 10:17 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

final fixes

79c2d33

mraszyk marked this pull request as ready for review April 28, 2026 10:25

mraszyk requested a review from a team as a code owner April 28, 2026 10:25

wording

206d93b

mraszyk requested a review from Copilot May 5, 2026 05:37

Copilot started reviewing on behalf of mraszyk May 5, 2026 05:38 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread docs/references/ic-interface-spec.md Outdated

typo

1a712a4

schneiderstefan approved these changes May 5, 2026

View reviewed changes

marc0olo approved these changes May 5, 2026

View reviewed changes

mraszyk added 2 commits May 5, 2026 10:15

Merge branch 'master' into mraszyk/effective-subnet-id

3c679e8

changelog

4c48a4e

mraszyk enabled auto-merge (squash) May 5, 2026 08:17

mraszyk merged commit 9d734b5 into master May 5, 2026
6 checks passed

mraszyk deleted the mraszyk/effective-subnet-id branch May 5, 2026 08:30

Conversation

mraszyk commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mraszyk commented Apr 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mraszyk commented Apr 15, 2026 •

edited

Loading