CIP-0030 | Encourage namespaced extension endpoints

[Ryun1]

Change

• Encourage that extension endpoints are explicitly namespaced by their cip/extension name.
  example: api.cip95.getPubDRepKey()

Motivation

I believe this is a sensible change to make ahead of the emergence of CIP-30 extensions, such as #509.

• This prevents extensions from creating conflicting endpoints with the same naming.
• This should help simplify wallet implementations, by allowing easier routing of requests.
• This should simplify extension management for dApps.

---

Thanks @stevenj and @refi93 for the suggestion.

[rphair]

On general principles (I'm not a dApp developer) I can see how the namespacing would be helpful. According to my understanding of these methods we wouldn't have a backward compatibility problem.

@refi93 @stevenj to fill out the reviews here, could you please summarise why you thought this was important & link to the relevant CIP-30 comments in any other GitHub PR threads where this was discussed? 🙏

[stevenj]

@rphair This was discussed in a meeting, so there are no notes.
But the discussion revolved around CIP-95 wanting to change the behavior of sign data when CIP-95 was enabled. And it seemed messy for both dApps and wallets to guarantee behavior. e.g., what if 2 independent CIP-30 extensions make changes to pre-existing functions? Which ones are active? What if they conflict in some way?

The cleanest way forward seemed to be to namespace the extension so that there could never be a collision, and the wallet could easily just provide the namespace APIs which are enabled, and not provide them if they are not. And if they are 90% identical internally, that's up to the wallet to sort out, which it can easily do.
Whereas dynamically changing pre-existing endpoint behavior seemed more complex.

For a dApp author, it also makes it clear that they are trying to get the enabled functionality, and it's no harder to call api.cipxx.something than it is to call api.something.
It's also more explicit rather than just implicit because of an enabled extension.

The CIP-62 draft defines a kind of namespacing as well, but it will be bought into line with this proposal if accepted.

[mirceahasegan]

For me, it is unclear how a DApp will use these namespaced methods.
Let's take signTx usage as an example:

1. DApp enables cip-95 and cip-1234.
2. Builds a transaction with Conway fields (e.g. registers a DRep certificate) + cip-1234-specific-stuff

Which signTx will the DApp use?

1. cip95.signTx(tx, partialSign=true) + cip1234.signTx(tx, partialSign=true)
2. Split it into 2 transactions and sign them separately?
3. Will all namespaced signTx extend the cip30 base sign?

[Ryun1]

This is a good question! and I think the answer would depend on how CIP-1234 defines it's signTx.

For me, I think it is best that extensions completely replace other extensions capabilities rather than dApps needing two extensions to do the same thing; such as signing transactions. So my preferred approach would be for CIP-1234 to be supporting all of the CIP-95 capabilities and it's own at once. This would prevent the need for dApps to support two extensions for the same purpose.

I also don't see this as a massive issue, as I don't see there being a massive emergence of conflicting extensions.

With that said, CIP-30 as it stands today would does allow for such awkward overlaps of capabilities between extensions and it is up to wallets to reconcile their capabilities, at enable time.

[mirceahasegan]

LGTM 🚀

[KtorZ]

I like the idea of name-spacing generally speaking; in that particular case, however, I think the possible clash is a desired feature of the whole extension scheme as it allows to issue new extensions to fix / patch / upgrade a previously published extension.

In a way, there's nothing preventing extensions to already use a namespace and perhaps we should encourage it: "new extensions MAY be under a specific namespace" but that "MUSTN'T", so we leave the door open to upgradable extensions. However, if namespaced then they should abide by a specific format (i.e. as proposed here cipXXXX)

[stevenj]

I like the idea of name-spacing generally speaking; in that particular case, however, I think the possible clash is a desired feature of the whole extension scheme as it allows to issue new extensions to fix / patch / upgrade a previously published extension.

In a way, there's nothing preventing extensions to already use a namespace and perhaps we should encourage it: "new extensions MAY be under a specific namespace" but that "MUSTN'T", so we leave the door open to upgradable extensions. However, if namespaced then they should abide by a specific format (i.e. as proposed here cipXXXX)

I agree generally. However, I see four possibilities:

1. The change does not change the Method signature, AND the functionality causes no harm if always enabled.
2. The change does not change the Method signature, BUT the functionality is incompatible with the previous behavior.
3. The method is NEW or changes the signature for an existing method.
4. it is a literal patch extension to a previous CIP.

An example of 1:
CIP-95 signTx Just adds new "types" of transactions the wallet understands. So even if CIP-95 was not enabled explicitly, it would cause no harm for signTx to just always allow them. All enabling the CIP does is give a signal to the wallet that signTX will allow the new certs to be signed.
This gives a way for multiple CIPs to add features to something like signTX as the ledger evolves. And each one just adds to the others. If I enable CIP-95 my dApp knows CIP-95 defined transactions can be signed. IF I enable CIP-1234 my dApp knows CIP-1234 signed transaction can be signed. That does not tell me anything about CIP-95, nor does my dapp care if it's not making CIP-95 transactions.
It should also be easy on the wallets, they don't need to "switch" behavior. Because supporting new transactions isn't harmful if a dApp never uses them. If it does, and the CIP isn't explicitly enabled, it's still not harmful in any way because they are always verified with the user anyway.

An example of 2:
signData is changed to add a rule that payload must be "BSON". signData can currently take ANY payload of bytes, so this breaks backward compatibility. If a third extension said payload must be "CBOR". If they are both enabled, then what does the wallet do? Is Payload "Anything", "BSON" only, OR "CBOR" only? In this case, it makes sense to me it should be in a namespace so that the functionality is completely unambiguous. Otherwise, how does one maintain consistent behavior across wallets? If I am making a new CIP do I need to scan every other CIP and make sure the behavior I propose isn't breaking to another CIP that also extends the same endpoint? Do CIP editors also need to do this? As the number of extensions grows this is going to become more and more difficult to manage.

An example of 3:
signData is changed to add a third optional parameter schema which is a JSON schema of the data being passed in payload so it can be better displayed to the User. This should be namespaced because it's not backward compatible, and it's feasible that someone sees this and says "I want the schema to also be CDDL" and makes another CIP to enable that, and you end up in #2 where what the wallet needs to do with all the possible permutations is ambiguous, and not easy to define in a backward or forwards compatible way.

In the case of 4, I think there should be a well-documented chain in the CIPs. Like a note added to the original CIP that says, this behavior of brokenMethod is deprecated, and dApps should enable CIP-777 to get the improved/fixed/patched behavior. The new CIP-777 could then say the same if it's patched (This is deprecated, see CIP-888 for new behavior). So that is unambiguous that CIP-888 is the best/latest version of the fixed/patched method. To me, however, this seems more complex to maintain and track than just making a namespace for the fixed method and not using the old one in the dApp

I would rather the default posture be "Namespace" unless it can be shown that the change proposed is backward and forwards compatible with existing behavior. And this should be on the proposer to justify. The new CIP should also be clear about it and discuss forward/backward compatibility reasoning.

[rphair]

Would there ever be a case where the a CIP-tagged namespace extension needed to be distinct by version number? Or would that just tack on as a different endpointX() undefined in the previous version?

If this specification implies that only the .cipNNN namespace is defined, and implementors are free to add other name subspaces after it, what would be the naming convention (e.g. endpoints like cipNNN.v?.endpointX())?

Whatever the preferred approach to the impact of CIP updates on the API, could this part of the document describe some recommendations about how to handle methods that are introduced or changed in newer versions?

If this was already covered in the meeting discussion, it went right over my head. As @Ryun1 you know I don't work with this material directly & just following on a question that came up in Discord here.

[Ryun1]

@rphair

Would there ever be a case where the a CIP-tagged namespace extension needed to be distinct by version number? Or would that just tack on as a different endpointX() undefined in the previous version?

I would be against this as it mixes two types of versioning at once, which I believe would be introduce unneeded complexity. Id much prefer to keep using the CIP extensions as a novel versioning scheme as outlined in CIP-30.

[Ryun1]

@stevenj @KtorZ

I agree with this approach! please check my wording on a4af1f3 🙏

[Scitz0]

One thing I noticed while adding the two new PRs for tx bulk signing and account pub is that you want to do reference implementations before CIP becomes active a gets a CIP number assigned. How are you supposed to namespace extensions before a number is assigned?

If you use a temporary namespace all reference implementations would then once a number is assigned have to update endpoints for this.

I guess this is not unique to this namespace change but affect also already merged Extension feature. Haven't actually checked if there is a method described there for how to handle this.

[Ryun1]

Hey @Scitz0,

How are you supposed to namespace extensions before a number is assigned?

Good question! I will amend this PR (in 2d7d6b6) to address this, I think I will follow the strategy outlined in #486. Let me know what you think! 🚀

[Ryun1]

As discussed in CIP Editors' Call 72, I have removed the overly prescriptive draft extension procedure.

My motivation for this;

• There is no need to prescribe such rigours process for draft extensions, it adds considerable overhead to authors/implementers.
• Using the experimental API should be enough for the vast majority of extensions.
• If an author wishes to use a more rigours process they are free to do so.

Does this match what was discussed in the meeting? @Crypto2099 @rphair

cc: @Scitz0

[rphair]

@Ryun1 👍 I do think the retraction gives us a lower common denominator that will improve use of the API without being too restrictive in the pathological cases we talked about this week.

[Scitz0]

Agree with change, no need to overcomplicate draft implementations. Experimental namespace is enough 👍

[mkazlauskas]

Do we have an actual use case for namespacing right now, or is this about future-proofing?

I do not understand the motivation:

This prevents extensions from creating conflicting endpoints with the same naming.

It does not seem to prevent it, as namespacing is optional. Also, why would we allow conflicting endpoints in the first place? If an endpoint does a different thing, then it can have a different name. We do not want to end up with 5 slightly different signTx methods and have to read through all the CIPs to figure out which one to use, also having to do fallbacks when some of them are unavailable - that's awful developer experience.

This should help simplify wallet implementations, by allowing easier routing of requests.

Might save a dozen lines of code for a wallet (probably only if namespacing was mandatory too) - don't see this as an issue.

This should simplify extension management for dApps.

Why/how? 🤔

---

Regarding the scenarios listed by @stevenj:

1. The change does not change the Method signature, AND the functionality causes no harm if always enabled.

As @stevenj wrote, there's no harm for wallet to support more than is being used. The dApp can also check whether new tx type is supported just by checking supportedExtensions. I don't think namespacing solves anything in this scenario.

2. The change does not change the Method signature, BUT the functionality is incompatible with the previous behavior.

signData is changed to add a rule that payload must be "BSON"

We can avoid the conflict simply via extension adding a new endpoint named signBSON rather than making a breaking change in the existing one. Or add an optional argument signData(addr, payload, { encoding: 'bson' }), keeping original behavior intact.

3. The method is NEW or changes the signature for an existing method.

signData is changed to add a third optional parameter schema which is a JSON schema of the data being passed in payload so it can be better displayed to the User. This should be namespaced because it's not backward compatible

I do not consider this a breaking change, because it's JavaScript. Yes, technically it can be breaking in some cases, but most of the time it wouldn't be and imho the risk here is tolerable to allow such changes to the API.

"I want the schema to also be CDDL" and makes another CIP to enable that, and you end up in # 2 where what the wallet needs to do with all the possible permutations is ambiguous, and not easy to define in a backward or forwards compatible way.

Well, the schema argument should've been added as { schema }, so # 2 can simply add { cddl }. It's up to the community and CIP editors to refine the designs before they are finalized. If we mess up and it's not possible to make a non-breaking change, then # 2 would add a new signCBOR endpoint.

4. it is a literal patch extension to a previous CIP.

Don't quite understand the problem here, but I suspect a similar append/extend-only solution would work too.

[Crypto2099]

I believe that this namespacing solution offers good future-proofing against a scenario where we have many extensions to this web wallet bridge. From both an implementer and developer perspective I would prefer namespace scoping to prevent global scope bloat leading to chaotic documentation and type hinting.

As written I see no hard barriers to following this standard as written and instead view the objections as more of a personal coding style preference versus any breaking objections. IMO it is easier to introduce namespace scoping now rather than attempting to retcon namespacing in the future when the namespace becomes intolerable.

[rphair]

Confirming #577 (review) as representing editor consensus in today's CIP meeting in the course of reviewing all discussion so far.