From 90bbdafa662384af8550c1a119d4396374ad9ab4 Mon Sep 17 00:00:00 2001 From: "Dieter M. Sommer" Date: Fri, 9 Aug 2024 09:21:59 +0200 Subject: [PATCH 1/6] Initial draft from issue --- ICRCs/ICRC-91/ICRC-91.md | 111 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 ICRCs/ICRC-91/ICRC-91.md diff --git a/ICRCs/ICRC-91/ICRC-91.md b/ICRCs/ICRC-91/ICRC-91.md new file mode 100644 index 00000000..76678755 --- /dev/null +++ b/ICRCs/ICRC-91/ICRC-91.md @@ -0,0 +1,111 @@ +# ic-http URI Scheme For Addressing Content of Canisters Exposed Via Their HTTP Interface + + +## Introduction + +Canister smart contracts on ICP can expose an HTTP interface that can be accessed from an HTTP client like a regular browser via an HTTP gateway. The HTTP Gateway Protocol Specification mandates regular HTTP URIs to specify a resource of a canister. That is, the HTTP URI for a canister contains the boundary node as the authority, or host name. This is inflexible as the URI contains a specific boundary node host name node and multiple different URIs with different boundary node hostnames refer to the same resource. + +Example: `.ic0.app/path/to/resource?par1=abcd&par2=efgh` + +Boundary node host names should be transparent for the addressing of HTTP resources. This standard introduces a new `ic-http` URI scheme which abstracts from the host name of the boundary node and thereby allows for uniquely referring to HTTP-exposed resources on the Internet Computer without reference to the boundary node's host name. This is crucial because with the opening up of the Internet Computer's edge infrastructure by allowing community-operated boundary nodes, there will be many host names available to access the same resource. + +For example, an NFT standard can use this mechanism to specify in NFT metadata HTTP-based canister-hosted resources of NFTs. Parties who read the metadata can transform the ic-http URIs to HTTP URIs with their preferred boundary node provider and load the resources with those URIs. + +This standard does not specify how to resolve the http-ic URI to a specific HTTP URI that can be accessed in a browser. This is left to future standards that are expected to evolve once the boundary node ecosystem is growing with further community participation. Such future standard would need to compose an HTTP URI from an http-ic URI based on the boundary node provider preference, and based on the preference choose a hostname. + +Note: not all boundary node providers will provide access to each canister. Thus, this constrains the transformation function from http-ic URIs to HTTP URIs. + + +## Background + +RFC-3986 specifies the syntax and semantics of URIs. The following grammar defines all valid URIs: + +``` + URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] + + hier-part = "//" authority path-abempty + / path-absolute + / path-rootless + / path-empty +``` + +For a new URI scheme, a subset of the language defined by this grammar needs to be defined. + + +## Specification + +The "ic-http" scheme is used to locate blockchain network resources exposed by ICP canisters via the HTTP semantics for IC-HTTP URIs independently of the hostname of the boundary nodes via which the resources can be accessed. + +URI schemes are lowercase according to [RFC-3986, Section 3.1](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1). + +The ic-http scheme defined in this standard has the following grammar expressed following the formal language put forth in RFC-5234: + + +``` + IC-HTTP-URI = "ic-http" ":" ic-http-hier-part [ "?" query ] [ "#" fragment ] + + ic-http-hier-part = "//" ic-canister-principal ic-http-path + + ic-canister-principal = 9*9( 5*5( base32char ) "-" ) 1*2( base32char ) + / 9*9( 5*5( base32char ) ) + / 1*8( 5*5( base32char ) "-" ) ( 1*5( base32char ) ) + / 1*5( base32char ) + + ic-http-path = path-abempty ; begins with "/" or is empty + / path-absolute ; begins with "/" but not "//" + / path-empty ; zero characters + + path-abempty = *( "/" segment ) + path-absolute = "/" [ segment-nz *( "/" segment ) ] + path-empty = 0 + segment = *pchar + segment-nz = 1*pchar + segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) + ; non-zero-length segment without any colon ":" + + query = *( pchar / "/" / "?" ) + + fragment = *( pchar / "/" / "?" ) + + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + pct-encoded = "%" HEXDIG HEXDIG + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "=" + pchar = unreserved / pct-encoded / sub-delims / ":" / "@" + base32char = base32letterlowercase / base32letterlowercase / base32digit + base32letterlowercase = a-z + base32letteruppercase = A-Z + base32digit = 2-7 +``` + +We refer the reader to [RFC-3986]([https://datatracker.ietf.org/doc/html/rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4)) for details on the components of a URI and [RFC-2234](https://datatracker.ietf.org/doc/html/rfc2234) for the definition of the productions in the above grammar that are not defined explicitly, such as `ALPHA` or `DIGIT`. + + +## Examples + +The following is an example for a regular HTTP URI +`https://by6od-j4aaa-aaaaa-qaadq-cai.ic0.app/token-1234/image?format=jpeg&res=high&hash=1234...abcd&hash_algorithm=sha256` + +The same URI expressed using the approach using an ic-http URI is the following: +`ic-http://by6od-j4aaa-aaaaa-qaadq-cai/token-1234/image?format=jpeg&res=high&hash=1234...abcd&hash_algorithm=sha256` + +FIX further examples to show all the features + + +## IANA Registration + +The current proposal has not yet been registered with [IANA's URI scheme registry](https://www.iana.org/assignments/uri-schemes) to make it an official URI scheme. This is a future step that should be taken once the approach has been sufficiently validated in reference implementations and found to be fit for the intended purpose. + + +## Conclusions + +With the boundary node edge infrastructure being opened up to community participants, additional boundary nodes with their own host names are expected to emerge. This ICRC standard is intended to unify the addressing of HTTP-exposed resources of canister smart contracts on the Internet Computer. It abstracts away the hostname of the boundary node used so far in HTTP URIs to address resources. This is important for any use case that references HTTP-exposed canister resources. + + +## References + +URI: https://datatracker.ietf.org/doc/html/rfc3986 +Syntax: https://datatracker.ietf.org/doc/html/rfc5234 +IANA URI scheme registry: https://www.iana.org/assignments/uri-schemes +Internet Computer HTTP Gateway Protocol Specification: https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec +Augmented BNF for Syntax Specifications: ABNF: https://datatracker.ietf.org/doc/html/rfc2234 \ No newline at end of file From bd54a50a850ab0c9c8f64d643d187d4bf5605f51 Mon Sep 17 00:00:00 2001 From: "Dieter M. Sommer" Date: Fri, 9 Aug 2024 10:08:56 +0200 Subject: [PATCH 2/6] Examples, references --- ICRCs/ICRC-91/ICRC-91.md | 104 +++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 52 deletions(-) diff --git a/ICRCs/ICRC-91/ICRC-91.md b/ICRCs/ICRC-91/ICRC-91.md index 76678755..63c50da3 100644 --- a/ICRCs/ICRC-91/ICRC-91.md +++ b/ICRCs/ICRC-91/ICRC-91.md @@ -5,7 +5,7 @@ Canister smart contracts on ICP can expose an HTTP interface that can be accessed from an HTTP client like a regular browser via an HTTP gateway. The HTTP Gateway Protocol Specification mandates regular HTTP URIs to specify a resource of a canister. That is, the HTTP URI for a canister contains the boundary node as the authority, or host name. This is inflexible as the URI contains a specific boundary node host name node and multiple different URIs with different boundary node hostnames refer to the same resource. -Example: `.ic0.app/path/to/resource?par1=abcd&par2=efgh` +Example: `dlbnd-beaaa-aaaaa-qaana-cai.ic0.app/tokens/12345678/image` Boundary node host names should be transparent for the addressing of HTTP resources. This standard introduces a new `ic-http` URI scheme which abstracts from the host name of the boundary node and thereby allows for uniquely referring to HTTP-exposed resources on the Internet Computer without reference to the boundary node's host name. This is crucial because with the opening up of the Internet Computer's edge infrastructure by allowing community-operated boundary nodes, there will be many host names available to access the same resource. @@ -18,18 +18,18 @@ Note: not all boundary node providers will provide access to each canister. Thus ## Background -RFC-3986 specifies the syntax and semantics of URIs. The following grammar defines all valid URIs: +[RFC-3986 \[BFM05\]](https://datatracker.ietf.org/doc/html/rfc3986) specifies the syntax and semantics of URIs. The following grammar defines all valid URIs: ``` - URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] + URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - hier-part = "//" authority path-abempty - / path-absolute - / path-rootless - / path-empty + hier-part = "//" authority path-abempty + / path-absolute + / path-rootless + / path-empty ``` -For a new URI scheme, a subset of the language defined by this grammar needs to be defined. +For a new URI scheme, like also for the ic-http scheme, a subset of the language defined by this grammar needs to be defined. ## Specification @@ -42,59 +42,60 @@ The ic-http scheme defined in this standard has the following grammar expressed ``` - IC-HTTP-URI = "ic-http" ":" ic-http-hier-part [ "?" query ] [ "#" fragment ] - - ic-http-hier-part = "//" ic-canister-principal ic-http-path - - ic-canister-principal = 9*9( 5*5( base32char ) "-" ) 1*2( base32char ) - / 9*9( 5*5( base32char ) ) - / 1*8( 5*5( base32char ) "-" ) ( 1*5( base32char ) ) - / 1*5( base32char ) - - ic-http-path = path-abempty ; begins with "/" or is empty - / path-absolute ; begins with "/" but not "//" - / path-empty ; zero characters - - path-abempty = *( "/" segment ) - path-absolute = "/" [ segment-nz *( "/" segment ) ] - path-empty = 0 - segment = *pchar - segment-nz = 1*pchar - segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) - ; non-zero-length segment without any colon ":" - - query = *( pchar / "/" / "?" ) - - fragment = *( pchar / "/" / "?" ) - - unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" - pct-encoded = "%" HEXDIG HEXDIG - sub-delims = "!" / "$" / "&" / "'" / "(" / ")" - / "*" / "+" / "," / ";" / "=" - pchar = unreserved / pct-encoded / sub-delims / ":" / "@" - base32char = base32letterlowercase / base32letterlowercase / base32digit - base32letterlowercase = a-z - base32letteruppercase = A-Z - base32digit = 2-7 + IC-HTTP-URI = "ic-http" ":" ic-http-hier-part [ "?" query ] [ "#" fragment ] + + ic-http-hier-part = "//" ic-canister-principal ic-http-path + + ic-canister-principal = 9*9( 5*5( base32char ) "-" ) 1*2( base32char ) + / 9*9( 5*5( base32char ) ) + / 1*8( 5*5( base32char ) "-" ) ( 1*5( base32char ) ) + / 1*5( base32char ) + + ic-http-path = path-abempty ; begins with "/" or is empty + / path-absolute ; begins with "/" but not "//" + / path-empty ; zero characters + + path-abempty = *( "/" segment ) + path-absolute = "/" [ segment-nz *( "/" segment ) ] + path-empty = 0 + segment = *pchar + segment-nz = 1*pchar + segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) + ; non-zero-length segment without any colon ":" + + query = *( pchar / "/" / "?" ) + + fragment = *( pchar / "/" / "?" ) + + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + pct-encoded = "%" HEXDIG HEXDIG + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "=" + pchar = unreserved / pct-encoded / sub-delims / ":" / "@" + base32char = base32letterlowercase / base32letterlowercase / base32digit + base32letterlowercase = a-z + base32letteruppercase = A-Z + base32digit = 2-7 ``` -We refer the reader to [RFC-3986]([https://datatracker.ietf.org/doc/html/rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4)) for details on the components of a URI and [RFC-2234](https://datatracker.ietf.org/doc/html/rfc2234) for the definition of the productions in the above grammar that are not defined explicitly, such as `ALPHA` or `DIGIT`. +We refer the reader to [RFC-3986 \[BFM05\]]([https://datatracker.ietf.org/doc/html/rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4)) for details on the components of a URI and [RFC-5234 \[CO08\]](https://datatracker.ietf.org/doc/html/rfc2234) for the definition of the productions in the above grammar that are not defined explicitly, such as `ALPHA` or `DIGIT`. ## Examples -The following is an example for a regular HTTP URI -`https://by6od-j4aaa-aaaaa-qaadq-cai.ic0.app/token-1234/image?format=jpeg&res=high&hash=1234...abcd&hash_algorithm=sha256` +The following is an example for a regular HTTP URI. The problem is that it includes the domain name for boundary nodes and thus is not generically referring to the resource on ICP, but referring to the resource through this specific boundary node domain. +`https://d6g4o-amaaa-aaaaa-qaaoq-cai.ic0.app/token/12345678/image?format=jpeg&res=high&hash=e18c9d041a3b66b794a37c52a49d1f4c9173c8aeadd6fc4cb1f3677d66873ddd&hash_algorithm=sha256` The same URI expressed using the approach using an ic-http URI is the following: -`ic-http://by6od-j4aaa-aaaaa-qaadq-cai/token-1234/image?format=jpeg&res=high&hash=1234...abcd&hash_algorithm=sha256` +`ic-http://d6g4o-amaaa-aaaaa-qaaoq-cai/token/12345678/image?format=jpeg&res=high&hash=e18c9d041a3b66b794a37c52a49d1f4c9173c8aeadd6fc4cb1f3677d66873ddd&hash_algorithm=sha256` +This URI expresses the resource on ICP in a generic way independent of any boundary node domain. FIX further examples to show all the features ## IANA Registration -The current proposal has not yet been registered with [IANA's URI scheme registry](https://www.iana.org/assignments/uri-schemes) to make it an official URI scheme. This is a future step that should be taken once the approach has been sufficiently validated in reference implementations and found to be fit for the intended purpose. +The current proposal has not yet been registered with [IANA's URI scheme registry](https://www.iana.org/assignments/uri-schemes) \[IANA\] to make it an official URI scheme. This is a future step that should be taken once the approach has been sufficiently validated in reference implementations and found to be fit for the intended purpose. ## Conclusions @@ -104,8 +105,7 @@ With the boundary node edge infrastructure being opened up to community particip ## References -URI: https://datatracker.ietf.org/doc/html/rfc3986 -Syntax: https://datatracker.ietf.org/doc/html/rfc5234 -IANA URI scheme registry: https://www.iana.org/assignments/uri-schemes -Internet Computer HTTP Gateway Protocol Specification: https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec -Augmented BNF for Syntax Specifications: ABNF: https://datatracker.ietf.org/doc/html/rfc2234 \ No newline at end of file +* [BFM05] T. Berners-Lee, R. Fielding, L. Masinter: Uniform Resource Identifier (URI): Generic Syntax. 2005, https://datatracker.ietf.org/doc/html/rfc3986 +* [CO08] D. Crocker, Ed., P. Overell: Augmented BNF for Syntax Specifications: ABNF. 2008, https://datatracker.ietf.org/doc/html/rfc5234 +* [IANA] IANA URI scheme registry. https://www.iana.org/assignments/uri-schemes +* [DFI24] DFINITY Foundation, The HTTP Gateway Protocol Specification. https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec, accessed July 2024 From 6ff0ef3ece10a9c6259761e8470447b30eb8c9f6 Mon Sep 17 00:00:00 2001 From: "Dieter M. Sommer" Date: Fri, 9 Aug 2024 10:17:15 +0200 Subject: [PATCH 3/6] Spec update --- ICRCs/ICRC-91/ICRC-91.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/ICRCs/ICRC-91/ICRC-91.md b/ICRCs/ICRC-91/ICRC-91.md index 63c50da3..805c01d4 100644 --- a/ICRCs/ICRC-91/ICRC-91.md +++ b/ICRCs/ICRC-91/ICRC-91.md @@ -29,16 +29,16 @@ Note: not all boundary node providers will provide access to each canister. Thus / path-empty ``` -For a new URI scheme, like also for the ic-http scheme, a subset of the language defined by this grammar needs to be defined. +For a new URI scheme, like also for the `ic-http` scheme, a subset of the language defined by this grammar needs to be defined. ## Specification -The "ic-http" scheme is used to locate blockchain network resources exposed by ICP canisters via the HTTP semantics for IC-HTTP URIs independently of the hostname of the boundary nodes via which the resources can be accessed. +The `ic-http` scheme is used to locate blockchain network resources exposed by ICP canisters via the HTTP semantics for IC-HTTP URIs independently of the hostname of the boundary nodes via which the resources can be accessed. -URI schemes are lowercase according to [RFC-3986, Section 3.1](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1). +We follow the specificiation of URI schemes being lowercase according to [RFC-3986, Section 3.1](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1). -The ic-http scheme defined in this standard has the following grammar expressed following the formal language put forth in RFC-5234: +The `ic-http` scheme defined in this standard has the following grammar expressed following the formal language put forth in RFC-5234: ``` @@ -84,28 +84,27 @@ We refer the reader to [RFC-3986 \[BFM05\]]([https://datatracker.ietf.org/doc/ht ## Examples The following is an example for a regular HTTP URI. The problem is that it includes the domain name for boundary nodes and thus is not generically referring to the resource on ICP, but referring to the resource through this specific boundary node domain. -`https://d6g4o-amaaa-aaaaa-qaaoq-cai.ic0.app/token/12345678/image?format=jpeg&res=high&hash=e18c9d041a3b66b794a37c52a49d1f4c9173c8aeadd6fc4cb1f3677d66873ddd&hash_algorithm=sha256` +`https://d6g4o-amaaa-aaaaa-qaaoq-cai.ic0.app/token/12345678/image?format=jpeg&res=high&hash=e18c9d041a3b66b794a37c52a49d1f4c9173c8aeadd6fc4cb1f3677d66873ddd` The same URI expressed using the approach using an ic-http URI is the following: -`ic-http://d6g4o-amaaa-aaaaa-qaaoq-cai/token/12345678/image?format=jpeg&res=high&hash=e18c9d041a3b66b794a37c52a49d1f4c9173c8aeadd6fc4cb1f3677d66873ddd&hash_algorithm=sha256` +`ic-http://d6g4o-amaaa-aaaaa-qaaoq-cai/token/12345678/image?format=jpeg&res=high&hash=e18c9d041a3b66b794a37c52a49d1f4c9173c8aeadd6fc4cb1f3677d66873ddd` This URI expresses the resource on ICP in a generic way independent of any boundary node domain. -FIX further examples to show all the features - - -## IANA Registration - -The current proposal has not yet been registered with [IANA's URI scheme registry](https://www.iana.org/assignments/uri-schemes) \[IANA\] to make it an official URI scheme. This is a future step that should be taken once the approach has been sufficiently validated in reference implementations and found to be fit for the intended purpose. +FIX further examples to show different use cases we consider important ## Conclusions With the boundary node edge infrastructure being opened up to community participants, additional boundary nodes with their own host names are expected to emerge. This ICRC standard is intended to unify the addressing of HTTP-exposed resources of canister smart contracts on the Internet Computer. It abstracts away the hostname of the boundary node used so far in HTTP URIs to address resources. This is important for any use case that references HTTP-exposed canister resources. +## Future Work + +The current proposal has not yet been registered with [IANA's URI scheme registry](https://www.iana.org/assignments/uri-schemes) \[IANA\] to make it an official URI scheme. This is a future step that should be taken once the approach has been sufficiently validated in reference implementations and found to be fit for the intended purpose. + ## References * [BFM05] T. Berners-Lee, R. Fielding, L. Masinter: Uniform Resource Identifier (URI): Generic Syntax. 2005, https://datatracker.ietf.org/doc/html/rfc3986 * [CO08] D. Crocker, Ed., P. Overell: Augmented BNF for Syntax Specifications: ABNF. 2008, https://datatracker.ietf.org/doc/html/rfc5234 * [IANA] IANA URI scheme registry. https://www.iana.org/assignments/uri-schemes -* [DFI24] DFINITY Foundation, The HTTP Gateway Protocol Specification. https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec, accessed July 2024 +* [DFI24] DFINITY Foundation, The HTTP Gateway Protocol Specification. Accessed July 2024, https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec From af947c2280e98ea66a04edfcab5f4da6eaa5de68 Mon Sep 17 00:00:00 2001 From: "Dieter M. Sommer" Date: Mon, 19 Aug 2024 14:01:11 +0200 Subject: [PATCH 4/6] Network identifier --- ICRCs/ICRC-91/ICRC-91.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/ICRCs/ICRC-91/ICRC-91.md b/ICRCs/ICRC-91/ICRC-91.md index 805c01d4..3a0c393e 100644 --- a/ICRCs/ICRC-91/ICRC-91.md +++ b/ICRCs/ICRC-91/ICRC-91.md @@ -5,10 +5,16 @@ Canister smart contracts on ICP can expose an HTTP interface that can be accessed from an HTTP client like a regular browser via an HTTP gateway. The HTTP Gateway Protocol Specification mandates regular HTTP URIs to specify a resource of a canister. That is, the HTTP URI for a canister contains the boundary node as the authority, or host name. This is inflexible as the URI contains a specific boundary node host name node and multiple different URIs with different boundary node hostnames refer to the same resource. -Example: `dlbnd-beaaa-aaaaa-qaana-cai.ic0.app/tokens/12345678/image` +Example: `https://dlbnd-beaaa-aaaaa-qaana-cai.ic0.app/tokens/12345678/image` Boundary node host names should be transparent for the addressing of HTTP resources. This standard introduces a new `ic-http` URI scheme which abstracts from the host name of the boundary node and thereby allows for uniquely referring to HTTP-exposed resources on the Internet Computer without reference to the boundary node's host name. This is crucial because with the opening up of the Internet Computer's edge infrastructure by allowing community-operated boundary nodes, there will be many host names available to access the same resource. +The above example would give the following URI using ICRC-91: +`ic-http://dlbnd-beaaa-aaaaa-qaana-cai/tokens/12345678/image` + +FIX: We should discuss to add a network id, e.g., (a prefix of) the hash of the DER-encoded network public key as unique identifier; this is important when we have private ICP-based networks or public testnets; we can have a default of ICP mainnet to keep it more convenient for the majority of use cases. The network could be added as top-level element in the authority hierarchy (`737ba355e855` is a prefix of the pub key hash) (we may want to add the full pb hash for reasons of security in order to not have collision potential with an adversarial's network) +`ic-http://dlbnd-beaaa-aaaaa-qaana-cai.737ba355e855/tokens/12345678/image` + For example, an NFT standard can use this mechanism to specify in NFT metadata HTTP-based canister-hosted resources of NFTs. Parties who read the metadata can transform the ic-http URIs to HTTP URIs with their preferred boundary node provider and load the resources with those URIs. This standard does not specify how to resolve the http-ic URI to a specific HTTP URI that can be accessed in a browser. This is left to future standards that are expected to evolve once the boundary node ecosystem is growing with further community participation. Such future standard would need to compose an HTTP URI from an http-ic URI based on the boundary node provider preference, and based on the preference choose a hostname. From 2d453f701e629bfc0b11ca195f9b8737b82adb88 Mon Sep 17 00:00:00 2001 From: "Dieter M. Sommer" Date: Tue, 20 Aug 2024 11:36:25 +0200 Subject: [PATCH 5/6] ICRC-91 update --- ICRCs/ICRC-91/ICRC-91.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/ICRCs/ICRC-91/ICRC-91.md b/ICRCs/ICRC-91/ICRC-91.md index 3a0c393e..e62d403e 100644 --- a/ICRCs/ICRC-91/ICRC-91.md +++ b/ICRCs/ICRC-91/ICRC-91.md @@ -1,30 +1,33 @@ # ic-http URI Scheme For Addressing Content of Canisters Exposed Via Their HTTP Interface +|ICRC|Title|Author|Discussions|Status|Type|Category|Created| +|:----:|:----:|:----:|:----:|:----:|:----:|:----:|:----:| +|91|ic-http URI Scheme For Addressing Content of Canisters Exposed Via Their HTTP Interface|Dieter Sommer (@dietersommer), Thomas (@sea-snake), Austin Fatheree (@skilesare)|https://github.com/dfinity/ICRC/issues/91|Draft|Standards Track||2024-08-09| ## Introduction -Canister smart contracts on ICP can expose an HTTP interface that can be accessed from an HTTP client like a regular browser via an HTTP gateway. The HTTP Gateway Protocol Specification mandates regular HTTP URIs to specify a resource of a canister. That is, the HTTP URI for a canister contains the boundary node as the authority, or host name. This is inflexible as the URI contains a specific boundary node host name node and multiple different URIs with different boundary node hostnames refer to the same resource. +Canister smart contracts on ICP can expose an HTTP interface that can be accessed from an HTTP client like a regular browser via an HTTP gateway. The HTTP Gateway Protocol Specification mandates regular HTTP URIs to specify a resource of a canister. That is, the HTTP URI for a canister contains the boundary node as the authority, or host name. This is inflexible as the URI contains a specific boundary node host name that resolves to a set of boundary nodes and multiple different URIs with different boundary node hostnames refer to the same resource. -Example: `https://dlbnd-beaaa-aaaaa-qaana-cai.ic0.app/tokens/12345678/image` +The following example shows a regular https URL,, which includes the hostname `ico.app` referring to a set of boundary nodes, to access a resource hosted by a canister: +`https://dlbnd-beaaa-aaaaa-qaana-cai.ic0.app/tokens/12345678/image` -Boundary node host names should be transparent for the addressing of HTTP resources. This standard introduces a new `ic-http` URI scheme which abstracts from the host name of the boundary node and thereby allows for uniquely referring to HTTP-exposed resources on the Internet Computer without reference to the boundary node's host name. This is crucial because with the opening up of the Internet Computer's edge infrastructure by allowing community-operated boundary nodes, there will be many host names available to access the same resource. +Boundary node host names should be transparent for the addressing of HTTP resources in order to be able to specify the resource independent of a specific boundary node host name. This standard introduces a new `ic-http` URI scheme which abstracts from the host name of the boundary node and thereby allows for uniquely referring to HTTP(S)-exposed resources on the Internet Computer without reference to the boundary node's host name. This is crucial in the light of the future architecture of ICP because with the opening up of the Internet Computer's edge infrastructure by allowing community-operated boundary nodes, there will be many host names available to access the same resource. The above example would give the following URI using ICRC-91: `ic-http://dlbnd-beaaa-aaaaa-qaana-cai/tokens/12345678/image` -FIX: We should discuss to add a network id, e.g., (a prefix of) the hash of the DER-encoded network public key as unique identifier; this is important when we have private ICP-based networks or public testnets; we can have a default of ICP mainnet to keep it more convenient for the majority of use cases. The network could be added as top-level element in the authority hierarchy (`737ba355e855` is a prefix of the pub key hash) (we may want to add the full pb hash for reasons of security in order to not have collision potential with an adversarial's network) +> [!NOTE] +> FIX: We should discuss to add a network id, e.g., (a prefix of) the hash of the DER-encoded network public key as unique identifier; this is important when we have private ICP-based networks or public testnets; we can have a default of ICP mainnet when omitting it to keep it more convenient for the majority of use cases. The network could be added as top-level element in the authority hierarchy (`737ba355e855` is a prefix of the pub key hash) (we may want to add the full pubkey hash for reasons of security in order to not have collision potential with an adversarial's network) `ic-http://dlbnd-beaaa-aaaaa-qaana-cai.737ba355e855/tokens/12345678/image` -For example, an NFT standard can use this mechanism to specify in NFT metadata HTTP-based canister-hosted resources of NFTs. Parties who read the metadata can transform the ic-http URIs to HTTP URIs with their preferred boundary node provider and load the resources with those URIs. +For example, an NFT standard can use this mechanism to specify HTTP-based canister-hosted resources of NFTs as part of NFT metadata. Parties who read the metadata can transform the `ic-http` URIs to HTTP URIs with their preferred boundary node provider and load the resources with those URIs. -This standard does not specify how to resolve the http-ic URI to a specific HTTP URI that can be accessed in a browser. This is left to future standards that are expected to evolve once the boundary node ecosystem is growing with further community participation. Such future standard would need to compose an HTTP URI from an http-ic URI based on the boundary node provider preference, and based on the preference choose a hostname. - -Note: not all boundary node providers will provide access to each canister. Thus, this constrains the transformation function from http-ic URIs to HTTP URIs. +This standard does not specify how to resolve a `http-ic` URI to a specific `https` URI that can be accessed in a browser. This is left to future ICRC standards that are expected to evolve once the boundary node ecosystem is growing with further community participation. Such future standard would need to compose an `https` URI from an `http-ic` URI based on the boundary node provider preference, and based on the preference choose a hostname. Not all boundary node providers will provide access to each canister on ICP. Thus, this constrains the transformation function from `http-ic` URIs to `https` URIs. A simple way to realize such transformation is with a registry of boundary node hostnames and canisters accessible through each boundary node to be available. ## Background -[RFC-3986 \[BFM05\]](https://datatracker.ietf.org/doc/html/rfc3986) specifies the syntax and semantics of URIs. The following grammar defines all valid URIs: +[RFC-3986 \[BFM05\]](https://datatracker.ietf.org/doc/html/rfc3986) specifies the syntax and semantics of URIs. The following grammar defines valid URIs: ``` URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] @@ -40,7 +43,7 @@ For a new URI scheme, like also for the `ic-http` scheme, a subset of the langua ## Specification -The `ic-http` scheme is used to locate blockchain network resources exposed by ICP canisters via the HTTP semantics for IC-HTTP URIs independently of the hostname of the boundary nodes via which the resources can be accessed. +The `ic-http` scheme is used to locate blockchain network resources exposed via the `https` protocol by ICP canisters independently of the hostname of the boundary nodes via which the resources can be accessed. We follow the specificiation of URI schemes being lowercase according to [RFC-3986, Section 3.1](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1). @@ -89,10 +92,10 @@ We refer the reader to [RFC-3986 \[BFM05\]]([https://datatracker.ietf.org/doc/ht ## Examples -The following is an example for a regular HTTP URI. The problem is that it includes the domain name for boundary nodes and thus is not generically referring to the resource on ICP, but referring to the resource through this specific boundary node domain. +The following is an example for a regular `https` URI. The problem is that it includes the domain name for boundary nodes and thus is not generically referring to the resource on ICP, but referring to the resource through this specific boundary node domain: `https://d6g4o-amaaa-aaaaa-qaaoq-cai.ic0.app/token/12345678/image?format=jpeg&res=high&hash=e18c9d041a3b66b794a37c52a49d1f4c9173c8aeadd6fc4cb1f3677d66873ddd` -The same URI expressed using the approach using an ic-http URI is the following: +The same URI expressed using the approach using an `ic-http` URI results in the following URI: `ic-http://d6g4o-amaaa-aaaaa-qaaoq-cai/token/12345678/image?format=jpeg&res=high&hash=e18c9d041a3b66b794a37c52a49d1f4c9173c8aeadd6fc4cb1f3677d66873ddd` This URI expresses the resource on ICP in a generic way independent of any boundary node domain. @@ -101,7 +104,7 @@ FIX further examples to show different use cases we consider important ## Conclusions -With the boundary node edge infrastructure being opened up to community participants, additional boundary nodes with their own host names are expected to emerge. This ICRC standard is intended to unify the addressing of HTTP-exposed resources of canister smart contracts on the Internet Computer. It abstracts away the hostname of the boundary node used so far in HTTP URIs to address resources. This is important for any use case that references HTTP-exposed canister resources. +With the boundary node edge infrastructure being opened up to community participants, additional sets of boundary nodes with their own host names are expected to emerge. This ICRC standard is intended to unify the addressing of `https`-exposed resources of canister smart contracts on the Internet Computer. It abstracts away the hostname of the boundary node used so far in `https` URIs to address resources. This is important for any use case that references `https`-exposed canister resources. ## Future Work From 9084f33a003ff6a720891175df4f9c34a3db03ff Mon Sep 17 00:00:00 2001 From: "Dieter M. Sommer" Date: Tue, 20 Aug 2024 12:03:17 +0200 Subject: [PATCH 6/6] Minor update --- ICRCs/ICRC-91/ICRC-91.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ICRCs/ICRC-91/ICRC-91.md b/ICRCs/ICRC-91/ICRC-91.md index e62d403e..8e84d224 100644 --- a/ICRCs/ICRC-91/ICRC-91.md +++ b/ICRCs/ICRC-91/ICRC-91.md @@ -49,7 +49,6 @@ We follow the specificiation of URI schemes being lowercase according to [RFC-39 The `ic-http` scheme defined in this standard has the following grammar expressed following the formal language put forth in RFC-5234: - ``` IC-HTTP-URI = "ic-http" ":" ic-http-hier-part [ "?" query ] [ "#" fragment ] @@ -106,9 +105,10 @@ FIX further examples to show different use cases we consider important With the boundary node edge infrastructure being opened up to community participants, additional sets of boundary nodes with their own host names are expected to emerge. This ICRC standard is intended to unify the addressing of `https`-exposed resources of canister smart contracts on the Internet Computer. It abstracts away the hostname of the boundary node used so far in `https` URIs to address resources. This is important for any use case that references `https`-exposed canister resources. + ## Future Work -The current proposal has not yet been registered with [IANA's URI scheme registry](https://www.iana.org/assignments/uri-schemes) \[IANA\] to make it an official URI scheme. This is a future step that should be taken once the approach has been sufficiently validated in reference implementations and found to be fit for the intended purpose. +The current proposal has not yet been registered with [IANA's URI scheme registry](https://www.iana.org/assignments/uri-schemes) \[IANA\] to make it an official URI scheme. This is a future step that should be taken once the approach has been sufficiently validated in reference implementations and found to be fit for the intended purpose. The `ic-http` URI scheme can already be used before registration to prove its usefulness. ## References