From 717b05ae1605b77307a9d627ad83e52606239f77 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 4 Aug 2023 18:32:53 +0100 Subject: [PATCH 1/8] stipulate namespaced extensions --- CIP-0030/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index 134608f57d..b40beb1833 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -200,6 +200,12 @@ Upon start, dApp can explicitly request a list of additional functionalities the DApps are expected to use this endpoint to perform an initial handshake and ensure that the wallet supports all their required functionalities. Note that it's possible for two extensions to be mutually incompatible (because they provide two conflicting features). While we may try to avoid this as much as possible while designing CIPs, it is also the responsability of wallet providers to assess whether they can support a given combination of extensions, or not. Hence wallets aren't expected to fail should they not recognize or not support a particular combination of extensions. Instead, they should decide what they enable and reflect their choice in the `cardano.{walletName}.extensions` field of the Full API. As a result, dApps may fail and inform their users or may use a different, less-efficient, strategy to cope with a lack of functionality. +Extension's endpoints should be namespaced by `.cipXXXX.` with the returned `API` object. For example; CIP-300's endpoints should be accessed by: + +```ts +api.cip300.endpoint() +``` + ##### Can extensions depend on other extensions? Yes. Extensions may have other extensions as pre-requisite. Some newer extensions may also invalidate functionality introduced by earlier extensions. There's no particular rule or constraints in that regards. Extensions are specified as CIP, and will define what it entails to enable them. @@ -368,6 +374,10 @@ Extensions can be seen as a smart versioning scheme. Except that, instead of bei 2. Not everyone agrees and has desired to support every existing standard; 3. There's a need from an API consumer standpoint to clearly identify what features are supported by providers. +#### Namespacing Extension + +By explicitly namespacing each enabled extension we aim to improve the usability of extensions for dApps. This prevents possible polymorphism of extension endpoints, which should also improve complexity of wallet implementations. + ## Path to Active ### Acceptance Criteria From 3a913c938412ed848632c7976c8b787ec507756d Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Mon, 7 Aug 2023 09:44:41 +0100 Subject: [PATCH 2/8] chose better number example --- CIP-0030/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index b40beb1833..14a5c8ed7b 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -200,10 +200,11 @@ Upon start, dApp can explicitly request a list of additional functionalities the DApps are expected to use this endpoint to perform an initial handshake and ensure that the wallet supports all their required functionalities. Note that it's possible for two extensions to be mutually incompatible (because they provide two conflicting features). While we may try to avoid this as much as possible while designing CIPs, it is also the responsability of wallet providers to assess whether they can support a given combination of extensions, or not. Hence wallets aren't expected to fail should they not recognize or not support a particular combination of extensions. Instead, they should decide what they enable and reflect their choice in the `cardano.{walletName}.extensions` field of the Full API. As a result, dApps may fail and inform their users or may use a different, less-efficient, strategy to cope with a lack of functionality. -Extension's endpoints should be namespaced by `.cipXXXX.` with the returned `API` object. For example; CIP-300's endpoints should be accessed by: +Extension's endpoints should be namespaced by `.cipXXXX.` with the returned `API` object. For example; CIP-1234's endpoints should be accessed by: ```ts -api.cip300.endpoint() +api.cip1234.endpoint1() +api.cip1234.endpoint2() ``` ##### Can extensions depend on other extensions? From bc52762bca6bc12a65d6a1c9905e0b1c9228445f Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Mon, 7 Aug 2023 17:38:09 +0100 Subject: [PATCH 3/8] Added removing leading zeros --- CIP-0030/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index 14a5c8ed7b..df5ab01a3f 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -200,11 +200,11 @@ Upon start, dApp can explicitly request a list of additional functionalities the DApps are expected to use this endpoint to perform an initial handshake and ensure that the wallet supports all their required functionalities. Note that it's possible for two extensions to be mutually incompatible (because they provide two conflicting features). While we may try to avoid this as much as possible while designing CIPs, it is also the responsability of wallet providers to assess whether they can support a given combination of extensions, or not. Hence wallets aren't expected to fail should they not recognize or not support a particular combination of extensions. Instead, they should decide what they enable and reflect their choice in the `cardano.{walletName}.extensions` field of the Full API. As a result, dApps may fail and inform their users or may use a different, less-efficient, strategy to cope with a lack of functionality. -Extension's endpoints should be namespaced by `.cipXXXX.` with the returned `API` object. For example; CIP-1234's endpoints should be accessed by: +Extension's endpoints should be namespaced by `.cipXXXX.` with the returned `API` object, without any leading zeros. For example; CIP-0123's endpoints should be accessed by: ```ts -api.cip1234.endpoint1() -api.cip1234.endpoint2() +api.cip123.endpoint1() +api.cip123.endpoint2() ``` ##### Can extensions depend on other extensions? From a4af1f395784bdc40fc2fdde94fb6d6712e9843a Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Thu, 17 Aug 2023 15:22:43 +0100 Subject: [PATCH 4/8] made namspacing partially optional --- CIP-0030/README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index df5ab01a3f..23db030d2a 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -200,13 +200,16 @@ Upon start, dApp can explicitly request a list of additional functionalities the DApps are expected to use this endpoint to perform an initial handshake and ensure that the wallet supports all their required functionalities. Note that it's possible for two extensions to be mutually incompatible (because they provide two conflicting features). While we may try to avoid this as much as possible while designing CIPs, it is also the responsability of wallet providers to assess whether they can support a given combination of extensions, or not. Hence wallets aren't expected to fail should they not recognize or not support a particular combination of extensions. Instead, they should decide what they enable and reflect their choice in the `cardano.{walletName}.extensions` field of the Full API. As a result, dApps may fail and inform their users or may use a different, less-efficient, strategy to cope with a lack of functionality. -Extension's endpoints should be namespaced by `.cipXXXX.` with the returned `API` object, without any leading zeros. For example; CIP-0123's endpoints should be accessed by: +It is at the extension author's discretion if they wish to separate their endpoints from the base API via namespacing. Although, it is highly recommend that authors do namespace all of their extensions. If namespaced, endpoints must be preceded by `.cipXXXX.` from the `API` object, without any leading zeros. +For example; CIP-0123's endpoints should be accessed by: ```ts api.cip123.endpoint1() api.cip123.endpoint2() ``` +Authors should be careful when omitting namespacing. Omission should only be considered when creating endpoints to override those defined in this specification or other extensions. Even so when overriding; the new functionality should not prevent dApps from accessing past functionality thus overriding must ensure backwards compatibility. + ##### Can extensions depend on other extensions? Yes. Extensions may have other extensions as pre-requisite. Some newer extensions may also invalidate functionality introduced by earlier extensions. There's no particular rule or constraints in that regards. Extensions are specified as CIP, and will define what it entails to enable them. @@ -377,7 +380,7 @@ Extensions can be seen as a smart versioning scheme. Except that, instead of bei #### Namespacing Extension -By explicitly namespacing each enabled extension we aim to improve the usability of extensions for dApps. This prevents possible polymorphism of extension endpoints, which should also improve complexity of wallet implementations. +By encouraging the explicit namespacing of each extension we aim to improve the usability of extensions for dApps. By allowing special cases where namespacing can be dropped we maintain good flexibility in extension design. ## Path to Active @@ -394,8 +397,8 @@ By explicitly namespacing each enabled extension we aim to improve the usability ### Implementation Plan - [x] Provide some reference implementation of wallet providers - - [Berry-Pool/nami-wallet](https://github.com/Berry-Pool/nami-wallet/blob/master/src/pages/Content/injected.js) - - [Emurgo/yoroi-wallet](https://github.com/Emurgo/yoroi-frontend/blob/develop/packages/yoroi-ergo-connector/src/inject.js) + - [Berry-Pool/nami-wallet](https://github.com/berry-pool/nami/blob/4d7539b2768464480a9cff53a2d66af9879f8534/src/pages/Content/injected.js) + - [Emurgo/yoroi-wallet](https://github.com/Emurgo/yoroi-frontend/blob/f4eabb25eedd564821514059479835601f8073ab/packages/yoroi-connector/example-cardano/index.js) - [x] Provide some reference implementation of the dapp connector - [cardano-foundation/connect-with-wallet](https://github.com/cardano-foundation/cardano-connect-with-wallet) From ba02ab514ff5707521d6c0417691e7b295aa9b8d Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 18 Aug 2023 14:25:00 +0100 Subject: [PATCH 5/8] added that authors have to justify --- CIP-0030/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index 23db030d2a..1eafb180b1 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -210,6 +210,8 @@ api.cip123.endpoint2() Authors should be careful when omitting namespacing. Omission should only be considered when creating endpoints to override those defined in this specification or other extensions. Even so when overriding; the new functionality should not prevent dApps from accessing past functionality thus overriding must ensure backwards compatibility. +Any namespace omission needs to be fully justified via the proposal's Rationale section, with explanation to why it is necessary. Any potential backwards compatibility considerations should be noted to give wallets and dApps a clear unambiguous direction. + ##### Can extensions depend on other extensions? Yes. Extensions may have other extensions as pre-requisite. Some newer extensions may also invalidate functionality introduced by earlier extensions. There's no particular rule or constraints in that regards. Extensions are specified as CIP, and will define what it entails to enable them. @@ -220,7 +222,7 @@ Yes. They all are CIPs. ##### Can extensions add their own endpoints and/or error codes? -Yes. Extensions may introduce new endpoints or error codes, and modify existing ones. Extensions may even change the rules outlined in this very proposal. The idea being that wallet providers should start off implementing this CIP, and then walk their way to implementing their chosen extensions. +Yes. Extensions may introduce new endpoints or error codes, and modify existing ones. Although, it is recommended that endpoints are namespaced. Extensions may even change the rules outlined in this very proposal. The idea being that wallet providers should start off implementing this CIP, and then walk their way to implementing their chosen extensions. ##### Are wallet expected to implement all extensions? From 2d7d6b6ccdf94ab783f554ee59c2eee6efc66b81 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Mon, 4 Sep 2023 22:58:33 +0100 Subject: [PATCH 6/8] address draft extensions --- CIP-0030/README.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index 1eafb180b1..aba4569708 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -212,6 +212,23 @@ Authors should be careful when omitting namespacing. Omission should only be con Any namespace omission needs to be fully justified via the proposal's Rationale section, with explanation to why it is necessary. Any potential backwards compatibility considerations should be noted to give wallets and dApps a clear unambiguous direction. +##### Draft or Experimental Extensions + +Extensions that are draft, in development, or prototyped should not use extension naming nor should they use official namspacing. + +Draft [Extension](#extension)s should instead be referred to as `"x-cip"`, and their number can be arbitrary and should not be expected to be unique. `"x-cip"` numbers should NOT be used with overlap official CIP or draft CIP assignments unless they are the draft extension for the respective CIP. Extensions without an officially assigned CIP number *MUST* use negative numbers until their proposal is officially assigned a number by the CIP process. Namespacing should use the associated `.x-cip`. + +For example a extension author (without an assigned number) could use: +```ts +{ "x-cip": -123 } +``` +with namespaced endpoints accessed by: +```ts +api.x-cip-123.endpoint1() +api.x-cip-123.endpoint2() +``` +When a CIP is ratified, the wallet may continue to recognize the `"x-cip"` extension. In this example, the finalized extension CIP that replaces the draft would be `{ "cip": 123 }`. This will allow for a graceful transition from draft to official status of extensions. How long a wallet or dApp will recognize the draft or experimental extension object is up to the individual wallet and dApp. + ##### Can extensions depend on other extensions? Yes. Extensions may have other extensions as pre-requisite. Some newer extensions may also invalidate functionality introduced by earlier extensions. There's no particular rule or constraints in that regards. Extensions are specified as CIP, and will define what it entails to enable them. @@ -380,7 +397,14 @@ Extensions can be seen as a smart versioning scheme. Except that, instead of bei 2. Not everyone agrees and has desired to support every existing standard; 3. There's a need from an API consumer standpoint to clearly identify what features are supported by providers. -#### Namespacing Extension +#### Draft Extensions + +The reason for using `"x-cip"` for drafts with an official number is to clearly distinguish between draft implementations and the official version. The official CIP can have differences from the final draft that both the dApp and wallet may need to accommodate. Avoiding using the official CIP extension until ratified disambiguates the draft process at the time of ratification. +This clearly distinguishing between them prevents avoidable compatibility errors should the final draft and ratified CIP differ. + +If a wallet is requested to enable both the draft and ratified CIP, it should **ALWAYS** prefer the ratified CIP. For example, a wallet that supported both CIP-62 final and draft would only enable the final CIP-62 extension if the request was to enable `(extensions: {[{"x-cip":62}, {"cip":62}]})`. + +#### Namespacing Extensions By encouraging the explicit namespacing of each extension we aim to improve the usability of extensions for dApps. By allowing special cases where namespacing can be dropped we maintain good flexibility in extension design. From 81e1ba3106df0475ba4309bd0cd33e0f2d82cdc1 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Sun, 10 Sep 2023 17:44:28 +0100 Subject: [PATCH 7/8] remove over perscriptive draft extension protocol --- CIP-0030/README.md | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index aba4569708..3d687de2fb 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -214,20 +214,7 @@ Any namespace omission needs to be fully justified via the proposal's Rationale ##### Draft or Experimental Extensions -Extensions that are draft, in development, or prototyped should not use extension naming nor should they use official namspacing. - -Draft [Extension](#extension)s should instead be referred to as `"x-cip"`, and their number can be arbitrary and should not be expected to be unique. `"x-cip"` numbers should NOT be used with overlap official CIP or draft CIP assignments unless they are the draft extension for the respective CIP. Extensions without an officially assigned CIP number *MUST* use negative numbers until their proposal is officially assigned a number by the CIP process. Namespacing should use the associated `.x-cip`. - -For example a extension author (without an assigned number) could use: -```ts -{ "x-cip": -123 } -``` -with namespaced endpoints accessed by: -```ts -api.x-cip-123.endpoint1() -api.x-cip-123.endpoint2() -``` -When a CIP is ratified, the wallet may continue to recognize the `"x-cip"` extension. In this example, the finalized extension CIP that replaces the draft would be `{ "cip": 123 }`. This will allow for a graceful transition from draft to official status of extensions. How long a wallet or dApp will recognize the draft or experimental extension object is up to the individual wallet and dApp. +Extensions that are draft, in development, or prototyped should not use extension naming nor should they use official namspacing until assigned a CIP number. Draft extension authors are free to test their implementation endpoints by using the [Experimental API](#experimental-api). ##### Can extensions depend on other extensions? @@ -397,13 +384,6 @@ Extensions can be seen as a smart versioning scheme. Except that, instead of bei 2. Not everyone agrees and has desired to support every existing standard; 3. There's a need from an API consumer standpoint to clearly identify what features are supported by providers. -#### Draft Extensions - -The reason for using `"x-cip"` for drafts with an official number is to clearly distinguish between draft implementations and the official version. The official CIP can have differences from the final draft that both the dApp and wallet may need to accommodate. Avoiding using the official CIP extension until ratified disambiguates the draft process at the time of ratification. -This clearly distinguishing between them prevents avoidable compatibility errors should the final draft and ratified CIP differ. - -If a wallet is requested to enable both the draft and ratified CIP, it should **ALWAYS** prefer the ratified CIP. For example, a wallet that supported both CIP-62 final and draft would only enable the final CIP-62 extension if the request was to enable `(extensions: {[{"x-cip":62}, {"cip":62}]})`. - #### Namespacing Extensions By encouraging the explicit namespacing of each extension we aim to improve the usability of extensions for dApps. By allowing special cases where namespacing can be dropped we maintain good flexibility in extension design. From f17bfab70c2aa06bfdc2a1def69c7c8630f70506 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Sun, 10 Sep 2023 17:48:27 +0100 Subject: [PATCH 8/8] small stipulation added --- CIP-0030/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CIP-0030/README.md b/CIP-0030/README.md index 3d687de2fb..60098351b6 100644 --- a/CIP-0030/README.md +++ b/CIP-0030/README.md @@ -214,7 +214,7 @@ Any namespace omission needs to be fully justified via the proposal's Rationale ##### Draft or Experimental Extensions -Extensions that are draft, in development, or prototyped should not use extension naming nor should they use official namspacing until assigned a CIP number. Draft extension authors are free to test their implementation endpoints by using the [Experimental API](#experimental-api). +Extensions that are draft, in development, or prototyped should not use extension naming nor should they use official namspacing until assigned a CIP number. Draft extension authors are free to test their implementation endpoints by using the [Experimental API](#experimental-api). Once a CIP number is assigned implementors should move functionality out of the experimental API. ##### Can extensions depend on other extensions?