diff --git a/AGENTS.md b/AGENTS.md index 2f9c48c..7f7dfca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -331,16 +331,20 @@ grep -r "{#}" docs/references/ic-interface-spec/ | Local file | Source | Affects | |-----------|--------|---------| | `public/reference/ic.did` | `.sources/portal/docs/references/_attachments/ic.did` | Management canister reference — new/changed methods require updating `docs/references/management-canister.md` | +| `public/references/_attachments/certificates.cddl` | `.sources/portal/docs/references/_attachments/certificates.cddl` | Downloadable CDDL linked from `docs/references/ic-interface-spec/certification.md` | +| `public/references/_attachments/requests.cddl` | `.sources/portal/docs/references/_attachments/requests.cddl` | Downloadable CDDL linked from `docs/references/ic-interface-spec/https-interface.md` | +| `public/references/_attachments/http-gateway.did` | `.sources/portal/docs/references/_attachments/http-gateway.did` | Downloadable Candid interface linked from `docs/references/http-gateway-spec.md` | | `docs/references/ic-interface-spec/` | `.sources/portal/docs/references/ic-interface-spec.md` | IC interface spec split into 7 focused pages — apply portal diffs by section (see checklist below) | | `docs/references/http-gateway-spec.md` | `.sources/portal/docs/references/http-gateway-protocol-spec.md` | HTTP Gateway spec — apply portal diff as a patch on every bump | **Portal bump checklist (run on every portal bump):** -**Step 1 — `ic.did`:** +**Step 1 — `ic.did` and `_attachments/`:** 1. `diff public/reference/ic.did .sources/portal/docs/references/_attachments/ic.did` 2. If changed: `cp .sources/portal/docs/references/_attachments/ic.did public/reference/ic.did` 3. Review diff for new/changed/removed methods 4. Update `docs/references/management-canister.md` and any affected guides +5. For each of `certificates.cddl`, `requests.cddl`, `http-gateway.did`: `diff public/references/_attachments/ .sources/portal/docs/references/_attachments/` — if changed, copy the updated file to `public/references/_attachments/` **Step 2 — `ic-interface-spec/`:** The spec is now split into 7 files under `docs/references/ic-interface-spec/`. Each file maps to a section of the portal source: @@ -383,6 +387,7 @@ git -C .sources/portal show -- docs/references/ic-interface-spec.md | g git -C .sources/portal log --oneline .. -- docs/references/_attachments/interface-spec-changelog.md git -C .sources/portal log --oneline .. -- docs/references/http-gateway-protocol-spec.md git -C .sources/portal log --oneline .. -- docs/references/_attachments/ic.did +git -C .sources/portal log --oneline .. -- docs/references/_attachments/certificates.cddl docs/references/_attachments/requests.cddl docs/references/_attachments/http-gateway.did ``` ## Planning artifacts (`.docs-plan/`) diff --git a/docs/references/http-gateway-spec.md b/docs/references/http-gateway-spec.md index e67ece8..c67fe9f 100644 --- a/docs/references/http-gateway-spec.md +++ b/docs/references/http-gateway-spec.md @@ -432,7 +432,7 @@ service : { } ``` -You can also [download the file](./_attachments/http-gateway.did). +You can also [download the file](/references/_attachments/http-gateway.did). Not all of this interface is required. The following sections detail what can be optionally omitted depending on the requirements of the canister in question. diff --git a/docs/references/ic-interface-spec/certification.md b/docs/references/ic-interface-spec/certification.md index 3c1acba..53d108f 100644 --- a/docs/references/ic-interface-spec/certification.md +++ b/docs/references/ic-interface-spec/certification.md @@ -179,7 +179,7 @@ Delegations are *scoped*, i.e., they indicate which set of canister principals t ### Encoding of certificates {#certification-encoding} -The binary encoding of a certificate is a CBOR (see [CBOR](./index.md#cbor)) value according to the following CDDL (see [CDDL](./index.md#cddl)). You can also [download the file](_attachments/certificates.cddl). +The binary encoding of a certificate is a CBOR (see [CBOR](./index.md#cbor)) value according to the following CDDL (see [CDDL](./index.md#cddl)). You can also [download the file](/references/_attachments/certificates.cddl). The values in the [The system state tree](./index.md#state-tree) are encoded to blobs as follows: diff --git a/docs/references/ic-interface-spec/https-interface.md b/docs/references/ic-interface-spec/https-interface.md index eddb2a1..544a277 100644 --- a/docs/references/ic-interface-spec/https-interface.md +++ b/docs/references/ic-interface-spec/https-interface.md @@ -735,7 +735,7 @@ A typical request would be (written in [CBOR diagnostic notation](https://www.rf ### CDDL description of requests and responses {#api-cddl} -This section summarizes the format of the CBOR data passed to and from the entry points described above. You can also [download the file](_attachments/requests.cddl) and see [CDDL](./index.md#cddl) for more information. +This section summarizes the format of the CBOR data passed to and from the entry points described above. You can also [download the file](/references/_attachments/requests.cddl) and see [CDDL](./index.md#cddl) for more information. ### Ordering guarantees diff --git a/public/references/_attachments/certificates.cddl b/public/references/_attachments/certificates.cddl new file mode 100644 index 0000000..f5ed44d --- /dev/null +++ b/public/references/_attachments/certificates.cddl @@ -0,0 +1,30 @@ +certificate = tagged<{ + tree : hash-tree + signature : signature + ? delegation : delegation +}> + +hash-tree = + tree-empty / + tree-fork / + tree-labeled / + tree-leaf / + tree-pruned + +; Trees are represented as CBOR arrays instead of records with textual field +; labels, for conciseness +tree-empty = [ 0 ] +tree-fork = [ 1 hash-tree hash-tree ] +tree-labeled = [ 2 bytes hash-tree ] +tree-leaf = [ 3 bytes ] +tree-pruned = [ 4 hash ] + +delegation = { + subnet_id : bytes + certificate: bytes +} + +tagged = #6.55799(t) ; the CBOR tag + +hash = bytes +signature = bytes diff --git a/public/references/_attachments/http-gateway.did b/public/references/_attachments/http-gateway.did new file mode 100644 index 0000000..3ec2d9c --- /dev/null +++ b/public/references/_attachments/http-gateway.did @@ -0,0 +1,49 @@ +type HeaderField = record { text; text; }; + +type HttpRequest = record { + method: text; + url: text; + headers: vec HeaderField; + body: blob; + certificate_version: opt nat16; +}; + +type HttpUpdateRequest = record { + method: text; + url: text; + headers: vec HeaderField; + body: blob; +}; + +type HttpResponse = record { + status_code: nat16; + headers: vec HeaderField; + body: blob; + upgrade : opt bool; + streaming_strategy: opt StreamingStrategy; +}; + +// Each canister that uses the streaming feature gets to choose their concrete +// type; the HTTP Gateway will treat it as an opaque value that is only fed to +// the callback method + +type StreamingToken = record { + // application-specific type +}; + +type StreamingCallbackHttpResponse = record { + body: blob; + token: opt StreamingToken; +}; + +type StreamingStrategy = variant { + Callback: record { + callback: func (StreamingToken) -> (opt StreamingCallbackHttpResponse) query; + token: StreamingToken; + }; +}; + +service : { + http_request: (request: HttpRequest) -> (HttpResponse) query; + http_request_update: (request: HttpUpdateRequest) -> (HttpResponse); +} diff --git a/public/references/_attachments/requests.cddl b/public/references/_attachments/requests.cddl new file mode 100644 index 0000000..c479e37 --- /dev/null +++ b/public/references/_attachments/requests.cddl @@ -0,0 +1,113 @@ +; The "root type" of the CDDL file is a hack: We want to define multiple +; types in one file (to shared common definitions), but CDDL requires a single +; root type. So we just list the types defined here. This is a common CDDL idiom. +start = + call-request / + read-state-request / + query-request / + read-state-response / + query-response + +; common wrappers + +tagged = #6.55799(t) ; the CBOR tag + +envelope = tagged<{ + content: t + ? sender_pubkey: pubkey + ? sender_delegation: [*4 signed-delegation] + ? sender_sig: signature +}> + + +; A request as submitted to /api/v2/.../call +call-request = envelope +call-request-content = { + request_type: "call" + ? nonce : bytes + ingress_expiry : timestamp + sender : principal + canister_id : principal + method_name : text + arg : bytes + ? sender_info : sender-info +} + +; A request as submitted to /api/v2/.../read_state +read-state-request = envelope +read-state-content = { + request_type: "read_state" + ? nonce : bytes + ingress_expiry : timestamp + sender : principal + paths: [* state-path] +} + +state-path = [* path-label] +path-label = bytes + +; The response, as returned from /api/v2/.../read_state +read-state-response = tagged<{ + certificate: bytes +}> + +; A request as submitted to /api/v2/.../query +query-request = envelope +query-content = { + request_type: "query" + ? nonce : bytes + ingress_expiry : timestamp + sender : principal + canister_id : principal + method_name : text + arg : bytes + ? sender_info : sender-info +} + +; The response, as returned from /api/v2/.../query +query-response = tagged<{ + status: "replied" + reply: call-reply + signatures: [+ node-signature] + // + status: "rejected" + reject_code: unsigned + reject_message: text + ? error_code: text + signatures: [+ node-signature] +}> + +sender-info = { + info : bytes + signer : principal + sig : signature +} + +node-signature = { + timestamp: timestamp + signature: bytes + identity: principal +} + +; user delegations + +signed-delegation = { + delegation: { + pubkey: bytes + expiration: timestamp + ? targets: [* principal] + } + signature: bytes +} + +; some common data types + +call-reply = { + arg : bytes +} + +principal = bytes .size (0..29) + +pubkey = bytes +signature = bytes +timestamp = unsigned