CAIP-25 General Discussion

[rekmarks]

I'm creating this discussion thread for discussing CAIP-25.

[kumavis]

by adding a handshake / session, we're layering a stateful protocol on top of a stateless protocol. so we must at least provide some guidance about the life cycle of the session.
what happens when we handshake multiple times? with different caip2 chain id?

[bumblefudge]

i'm embarassed to have just seen this-- this very issue was discussed at many CASA meetings since and resulted in this PR which would, I'm sure, greatly appreciate your review! Since September we've pushed the session management into a separate CAIP somewhat, and your colleague @hmalik88 has been leading discussion of this at the biweekly calls so feel free to coordinate with him to propose alternate times if you'd like to attend one!

[adonesky1]

@bumblefudge I'd like to loop back here on the threads we were discussing in our call this week:

1. Where should RPC connection metadata live in the CAIP-25 request.

Briefly rehashing what we’re after here: In MetaMask we require certain metadata for users to add networks to their wallet (or for dapps to propose adding a network to a users wallet). I assume that the inclusion of rpcEndpoints in the CAIP-217 scopeObject was intended to facilitate wallet connections with previously unknown networks. At MetaMask would like to enable this feature with our CAIP-25 implementation however we cannot safely add new networks with only the chainid (from the CAIP-2 scopeObject key) and an url from the rpcEndpoints array. Unfortunately there are not methods like eth_chainid to query for all of the metadata we need - chainName, nativeCurrency ticker, nativeCurrency decimals and optionally blockExplorer links - and therefore we are forced to rely on 3rd party canonical lists for validation against the attestations of users and dapps. Because we consider this metadata prerequisite to connection we think there is a case to include a connectionMetadata property on the CAIP-217 scope object with instructions that wallets should validate the information against canonical lists. In the call it sounded like your preference would be to add this metadata in a map in the sessionProperties of the request. Let’s continue this discussion here and hopefully make a swift decision.

|

2. SessionIds shouldn’t be required.

MetaMask has long lived connections with dapps in which the permissions granted via CAIP-25 requests are the single source of truth for the account/methods/chains permissions until they are revoked. In our current model these permissions persist if the user closes and reopens the dapp any number of times without any required re-instantiation of the permissions upon reconnection. Making sessionIds optional, allows the standard to be more agnostic to how wallets/dapps choose to manage their sessions. In some cases - as I assume for WC - permissions could be more tightly coupled to the actual connection between wallet and dapp or have an expiry in which cases its valuable for both sides to hold on to a sessionId to ensure they’re on the same page regarding the scope and status of the session. In our case we simply persist the permissions (by hostname) until revoked and allow the dapp to ask (via wallet_getPermissions) what the state of their permissions are if they choose not to store a record on their end.

A message from @hmalik88 on this topic: “My position on the matter is pretty much simple, we should loosen the requirements around session ids to allow for more flexibility around client implementations of their respective permission systems. Not require session ids to be returned but if they are they should follow the already outlined requirements.” 


3. Revoking Permissions:

Currently CAIP-25 doesn’t clearly provide a path other than for creating a new sessions to revoke a previous session. Consider a “logout” or “disconnect” button on dapp in which a user wishes to fully terminate a session, how does a dapp implementating CAIP-25 handle such operations?

4. CAIP-217 shouldn’t allow namespace wild carded scopeObjects.

We believe its not desirable to allow for permissioning unenumerated chains as is currently allowed in CAIP-25/217:

CAIPs/CAIPs/caip-217.md

Line 76 in b01678c

- This property MAY be present if the scope is an entire [namespace][namespaces] in which `chainId`s are defined.

This seems generally insecure but also makes adding incremental permissions for any given sub scope very complex.

[glitch-txs]

Because we consider this metadata prerequisite to connection we think there is a case to include a connectionMetadata property on the CAIP-217 scope object with instructions that wallets should validate the information against canonical lists.

How would a wallet handle such amount of approval requests in a "single request"? Users should also be able to see IMO what they are approving (adding a new chain to the wallet's list). Let's say a dapp has 5 chains and the wallet has only 1 registered. It would need to approve and verify the metadata of 4 chains. Adding to this at WalletConnect we've started implementing One Click Auth which unifies the connection request with a signature request. In terms of UX I think this might get to be a lot of information for a user to approve on a single approval req.

IMO the ability of updating sessions dynamically might offer a better UX, currently MetaMask does this implicitly when wallet_switchEthereumChain or wallet_addEthereumChain are called. Maybe we could improve the way sessions are updated to make them more explicit?

[bumblefudge]

1. I definitely see the value in chain metadata but I'm still not sold on including it along with chain connection data in the authorization document. In the WC use-case, that metadata just categorically lives on another level and it feels a little to we're mixing [very human] trust decisions into what is currently a machine-readable protocol. My preference layering-wise would still be to put metadata needed for trust decisions in the sessionProperties since they are annotations and kind of use-case specific, but maybe I can be convinced. Would also love to hear @pedrouid or @rekmarks to chime in here, I feel like they would both have strong opinions about chain metadata and chain-trust more generally.

2. I like Hassan's point about handling them as written if they're provided by the wallet-- i'm just unclear on how wallets not generating one and returning one in the initial call should be treated. Should the dapp just generate one and use one as normal for the session?

More generally I still have some questions about the non-session session that is persisted and has no hard-reset button. If a wallet auto-generates the sessionId for tracking on their end the perma-session with a given MM extension wallet, and then the computer on which the latter lives gets clean-slated, OS reinstalled, and wallet re-installed, recovered from private key backup. Like the ship of Theseus, is it the same wallet? Even if it's persistence of those permissions wasn't restored, and the dapp can't tell the difference? In this "restored wallet, but with local storage/memory lost" user-story, wouldn't a new sessionId from the amnesiac wallet be a useful signal to the dapp that even though the same wallet controlling the same account has logged back in, it is not the same connection and the persistence it would normally expect from an expiration-free connection has been lost? A permanent connection that lasts as long as the extension wallet lasts still feels like one session to me.

Also would love to hear an update from @ritave since, as far as I can remember, he had strong opinions about the perma-session!

3. Sending a new sessionId even before the last one is expired was meant to "reset" the connection and signal to the dapp that this new session replaced the prior one! We discussed even making this more explicit (i.e., "don't allow a given account to be controlled by two different active/ongoing sessions") but opted not to constrain the design space. Perhaps a backpointer to the old sessionId from, say, sessionProperties would be useful here 😏

4. Are you suggesting we change that "MAY" to a "MUST"? I might be OK with that if no one objects, honestly, I think less dapps that expected have actually used this as designed. I actually tend to agree that the best (maybe only legitimate) use-case for namespace-wide scope objects is when 3 or 4 (or initially 3, then 4, then 5...) identical chains get authorized according to a set "profile", and additional chains can be "carbon-copied" onto the list. You lost me a little on the incremental permissions for subscopes, but maybe it would help to reframe the situation thusly:

An eip155 namespace with scopes property of {1, 56, 42161} and 6 methods and 2 events is functionally the same as 3 different scopes, {eip155:1, eip155:56, eip155:42161}`, each defined with the exact same 6 methods and 2 events.

The latter is a clear winner if there's any reasonable chance the contents of those three scope objects might differ, initally or over time-- if you need incremental permissions for "subscopes" then you could and should just makes split them out into separate scopes! There are use-cases for both (1 scope per chain, easy for them to diverge, versus 1 scope for all, which all gain or lose members together), but introducing the term "subscope" implies you are squarely in the former set of use-cases.

[bumblefudge]

also @adonesky1 another followup on # 2 -- i think CAIP-27 was designed to be as lightweight as possible, using sessionIds to "target" a given wallet with which a CAIP-25 session is currently open. how does CAIP-27 work with persistent/stay-open connections? could dapps still call CAIP-27 if a wallet has closed the connection without resetting/overwriting/replacing the sessionId?

[adonesky1]

How would a wallet handle such amount of approval requests in a "single request"? Users should also be able to see IMO what they are approving (adding a new chain to the wallet's list). Let's say a dapp has 5 chains and the wallet has only 1 registered. It would need to approve and verify the metadata of 4 chains. Adding to this at WalletConnect we've started implementing One Click Auth which unifies the connection request with a signature request. In terms of UX I think this might get to be a lot of information for a user to approve on a single approval req.

@glitch-txs
We have designed with this concern in mind. For requiredScopes we would foreground the need to add networks that are not in the users wallet, since the connection request will necessarily fail if the user does not have the required network in their wallet. Without connection metadata in the request then we would have to reject the request, the dapp would then prompt the user with this same connection metadata in a separate wallet_addEthereumChain request and then reprompt a CAIP-25 request now that the wallet has the prerequisite network installed. This seems like an unnecessarily suboptimal flow. Of course - like WC - we won't recommend requiredScopes for most use cases. For optionalScopes we would never be forcing (or even really foregrounding the option) to add networks missing from their wallet, but would like to offer a path in the connection flow to do so should the user want. We also plan to preserve the wallet_addEthereumChain flow of course and provide a progressive/incremental path for dapps/wallets to build the full set of capabilities and permissions required, but we view it as preferable to offer both paths - a "full kitchen sink" connection flow for users who prefer it and an incremental path for those prefer that. I think the best argument for adding connection metadata in the scope itself is that it may be prerequisite for a successful connection. But ultimately we're just debating whether this data lives in the scope object or in sessionProperties...

[adonesky1]

I like Hassan's point about handling them as written if they're provided by the wallet-- i'm just unclear on how wallets not generating one and returning one in the initial call should be treated. Should the dapp just generate one and use one as normal for the session?

I take Hassan to be saying (and what I'm saying) is that some wallets will use sessionIds and others simply will not

In this "restored wallet, but with local storage/memory lost" user-story, wouldn't a new sessionId from the amnesiac wallet be a useful signal to the dapp that even though the same wallet controlling the same account has logged back in, it is not the same connection and the persistence it would normally expect from an expiration-free connection has been lost?

Ok so just so I'm clear on this flow you're imagining when this blanked out wallet comes back:

• The dapp says hey I have an active session with this wallet let me try to make a request so it makes a CAIP-27 request with the old sessionII. Then the wallet says hey I don't know that sessionId and sends back a failure/rejection response with a new sessionId indicating the previous session was closed?
  What does this achieve that can't be achieved by the dapp simply requesting wallet_getPermissions before it wants to send another request?

It seems to me the value of the sessionId is premised on the idea that both parties are always storing the permissions state. What if the dapp doesn't do so across refresh? Does this mean that the dapp will just request new permissions since it doesn't recognize the sessionId and therefore doesn't know what permissions it has? Why not just let the wallet be the single source of truth for permissions (if it wants to be) which the dapp can always query? I suppose you could argue that making the permissions set queryable is leaky but insofar as sessionIds are premised on the dapp tracking this info on its own it seems like the same thing to me.

@bumblefudge

[adonesky1]

i think CAIP-27 was designed to be as lightweight as possible, using sessionIds to "target" a given wallet with which a CAIP-25 session is currently open. how does CAIP-27 work with persistent/stay-open connections? could dapps still call CAIP-27 if a wallet has closed the connection without resetting/overwriting/replacing the sessionId?

dapps could call CAIP-27 (no sessionId required in CAIP-27 either in this approach I'm proposing) to the wallet as long as the permissions established in the CAIP-25 handshake(s) cover the method in the CAIP-27 request and they have not been revoked (via an equivalent to wallet_revokePermissions, which is the subject of my #3 question) or the wallet hasn't been wiped for some reason per your wallet of theseus scenario above

[adonesky1]

Sending a new sessionId even before the last one is expired was meant to "reset" the connection and signal to the dapp that this new session replaced the prior one! We discussed even making this more explicit (i.e., "don't allow a given account to be controlled by two different active/ongoing sessions") but opted not to constrain the design space. Perhaps a backpointer to the old sessionId from, say, sessionProperties would be useful here 😏

🤔 so lets assume for now that we will use sessionIds in MetaMask, lets say a dapp has a "disconnect" or "logout" button and the user clicks it, it we wanted to fully end that "session" and not create a new one would we send a provider_authorize request with a new sessionId and no scopes?

Ok now humor me and say sessionIds are optional (per #2 ☝️) and MetaMask is not using them at all, how then would we revoke a previous "sessions" permissions? I think perhaps there could/should be a separate method for this revocation operation?

@bumblefudge

[bumblefudge]

wouldn't an "empty" (no scopes) request and the OLD sessionId be the most explicit and unambigious reset/disconnect signal?

[bumblefudge]

definitely need a separate revoke method if sessionIds go optional, that's for sure. sessionId was the lynchpin in all of this, but as Hassan mentions below, it might distribute compute/grief inelegantly, so rejiggering the whole lifecycle might be justified.

[hmalik88]

I think it makes sense to have a revoke permissions method, CAIP-25 is being overloaded in a sense with many different concerns. I.e.:

1. Session Id in session properties + hasPermissionDiff() (a new computational load for the client) === true ----> session update
2. No session id ----> new session
3. Session id in session properties + empty scopes ----> ??? (active session or closed session? what does open session entail? Seems like a dapp dependent design problem)

Would be cool to have a separation of concerns with something like provider_authorize (initial connection request), provider_update (update request with or w/o session id) and provider_revoke (revoke either a part or the entire permission set granted for that session, what session is for the client is dependent on their permission system implementation). Clients can also map these methods to their own internal implementations so as to make the specifications for the respective methods generic.

[bumblefudge]

OK this is pretty convincing, let's hash it out and make a gameplan here, it might solve some of these other problems collaterally

[rekmarks]

I was summoned. Here are my quick takes:

1. connectionMetadata

It's fine to just stick this under sessionProperties. It doesn't need to be a top-level key.

On the other hand, it also seems fine to add it as an optional top-level property. I suppose you can call me agnostic.

2. sessionId, required or not?

As @adonesky1 explained, MetaMask does not need this property in many cases. That said, we can generate a UUID per dapp and just keep that until the end of time or when the user disconnects. The existence of session IDs doesn't really hurt those who don't need it.

Point of clarification: I don't think the "ship of theseus" hypothetical that @bumblefudge elaborated is in fact possible for an extension wallet, or MM mobile's in-app browser for that matter. Even if the dapp stored an old session id in its backend, it seems unlikely that it would be able to identify MM as the same wallet under those circumstances.

3. Revoking permissions

We will support this functionality in an incremental fashion (just like we will support incrementally adding things to an existing CAIP-25 session), and to @hmalik88's point, we perhaps should standardize something like provider_update (using a better word than "update" to strictly imply an increase in authority) and provider_revoke at CASA as well. Our current work on these matters could inform such standards.

4. Wildcard scopes?

I think it's fine if this stays in the standard as optional, but we have no current plans to support it either way.

Edit: Our "lack of support" for this will entail rejecting wildcarded requests as too broad on behalf of the user, and we may change our minds about this depending on feedback from dapps and users.

[bumblefudge]

3.) provide_escalate and provider_revoke sound good, let's go!

2.) My biggest hesitation about making sessionId's optional is that the complexity of updating and revoking permissions goes up a lot if we have to think through each case with and without sessionIds-- simpler to require sessionIds and make them the mechanism of updates and revocations. If we're making separate functions, and really spec out the lifecycle better across separate calls, my defensiveness about sessionId should pass away gradually...

Apologies for the lag in responding, I was AFK essentially all of May!

[adonesky1]

If we're making separate functions, and really spec out the lifecycle better across separate calls, my defensiveness about sessionId should pass away gradually...

Per my message here I think I strong prefer the new methods provider_escalate, provider_revoke and provider_getAuthorization (or something like that for consumers to inspect current permissions) to manage the lifecycle. I feel this would reduce additional undue burden on wallets with connection lifecycles like ours (probably all browser extension wallets).

[adonesky1]

We're planning to draft out CAIPs for these methods btw

[adonesky1]

Wanted to drop in another thought here:

While I get the impulse behind requiredScopes - it allows the API to be more expressive - I am beginning to feel that the benefits don't outweigh two major issues I see with it:

1. The risk of misuse that leads to bad UX. WalletConnect has already seen these issues as you're well aware.
2. The additional headache of having to design for the rare cases where dapps actually want requiredScopes

I have yet to encounter a dapp where the requiredScope actually makes sense to me. It really only makes sense if you have 2 or more networks required without which the dapp literally cannot function, since if you need just one network its already required to have atleast one scope in optionalScopes. And even in cases where dapps actually want this its trivially easy for the dapp to communicate that it cannot work unless you grant these permissions.

[adonesky1]

since if you need just one network its already required to have atleast one scope in optionalScopes

Just want to clarify what I meant here: If a dapp specifies one chain in optionalScopes (and no requiredScopes) and the wallet user doesn't accept that scope, the whole request must be rejected meaning that in this case this optional scope behaves the same as a requiredScope.

[bumblefudge]

I'd say that WC is encouraging no requiredScopes, only optionalScopes, and I agree that there are currently few corner cases where 2 chains should both be mandatory (more common are cases were 1 of 2 must be supported). That said, I do think it's kind of future-proof, in a way, and will be more useful over time, to have the option of requiredScopes, so I'm inclined to leave it as a kind of "conformant but not used anywhere" codepath for now. In any case, my feelings here are pretty weak, and it feels less urgent than the other stuff being discussed here!

[adonesky1]

1. connectionMetadata
   It's fine to just stick this under sessionProperties. It doesn't need to be a top-level key.
   On the other hand, it also seems fine to add it as an optional top-level property. I suppose you can call me agnostic.

Just want to loop back to this topic: @bumblefudge I hear your point:

it feels a little to we're mixing [very human] trust decisions into what is currently a machine-readable protocol

But it still feels like it would be better to have some kindof options bucket where you can mixin some subjective/trust based values rather than polluting the sessionProperties with another mapping when sessionProperties really feels like it should be for values that are scoped to the entire session?

[bumblefudge]

well, it kinda depends whether you are conceiving of a session as longlived/persistent or more like a browser session-- if the latter, putting config in there IS actually what it "should be for" (or at least, was intended for), i.e. short-lived variables specific to the session, not the lifelong/cross-device connection. i don't think we're polluting the miscellaneous category but putting config miscellany among the other miscellany 😄

[adonesky1]

@rekmarks

MetaMask does not need this property in many cases. That said, we can generate a UUID per dapp and just keep that until the end of time or when the user disconnects. The existence of session IDs doesn't really hurt those who don't need it.

At the same time it does make new requirements of dapps interfacing with the extension. Now those dapps need to keep track of this sessionId and if they somehow lose it and say hey let me send a new one they lose all their permissions and have to request them again, instead of what they could do today in that scenario (if they lost track of what permissions they have) they could just call wallet_getPermissions and be on their jolly way. This latter approach seems preferable to me...

[rekmarks]

I think there are various ways to mitigate this problem, and the handling thereof can simply be delegated to connector / adapter libraries that we or the usual suspects (WalletConnect, web3onboard, etc.) develop. In any event, storing a string in localStorage is not an onerous requirements, and we could even keep track of session ids on our end and simply resurrect existing sessions when possible.

[Gudahtt]

Storage does make the connector/adapter/provider API more complicated. We'd have to at least optionally allow custom storage, not just blindly store things in local storage. Web applications might reasonably assume that nothing else uses local storage.

I don't doubt that we can come up with a reasonable solution here, but this would be a significant shift for dapps (from stateless to state-based connections).

[rekmarks]

I don't doubt that we can come up with a reasonable solution here, but this would be a significant shift for dapps (from stateless to state-based connections).

That's fair. I don't know if this is a good idea, but we could potentially emulate statelessness by using fixed, deterministic session ids in cases where the session id has no security implications (e.g. websites connected to the extension). This would technically violate CAIP-25, 27 (probably), and 171, but not in a way that would be breaking for dapps or WalletConnect.

[pedrouid]

Sorry folks for not being active here but as you can imagine CAIP-25 is a very important spec for WalletConnect protocol and I would like to chime in on several topics that were discussed here

1. optional sessionId - personally I don't think it would be detrimental to make sessionId optional HOWEVER I can only see benefits for making it required because it ties together a lot of the UX where we can send follow-up signing requests with CAIP-27 and potentially introduce methods to update, extend or revoke the session using the sessionId... if we do make sessionId optional then it would be very unlikely that is undefined for most cases

2. update/extend/revoke - this is something that WalletConnect already supports and honestly I think it would be very beneficial for us to standardize as CAIPs... the majority of the logic has already been worked out with CAIP-25 so introducing these methods should be fairly to make it backwards-compatible and most likely won't break compatibility at all

3. scope objects - please please please don't touch these too much or at all... we already spent so many months discussing these and made so many changes until the very last day of WalletConnect v2.0 mgiration... honestly they are so flexible and extendable that I would see very little reason to break compability here

4. required scopes - now that WalletConnect v2.0 has been in production with billions of connections for almost 2 years it has been proven that required scopes were not very beneficial... the reality is that multi-chain applications and wallets are terrible and they don't have the maturity to handle these requiredScopes so we found a lot of obstacles with it... WalletConnect protocol today is used almost exclusively with optional scopes therefore removing required scopes would not break anything in our stack and we could potentially clean up a lot of our logic

5. connection metadata - maybe we need to make this clearer in the spec but just the fact that we are discussing any form of metadata then it should be clear that it should always go under sessionProperties... all important or critical information was already included in the scope object which includes accounts, chains, methods, notifications, rpcUrls and rpcDocs... then externally we have the sessionId to allow us to use future methods like provider_request and eventually other methods to update, extend and revoke ... you can even see expiry being defined under sessionProperties so please use the session properties for any other metadata

[adonesky1]

Crossposting this for visibility. I've opened a new CAIP proposal to add "lifecycle" methods as an alternative to session lifecycle management via sessionId

[pedrouid]

Thank you so much for the productive discussion yesterday @adonesky1 🙌

Looking forward to see your CAIP-285 updated with more context around the lifecycles

Also to follow-up on the method renaming I would like to propose the following:

• provider_authorize (CAIP-25) -> wallet_createSession or wallet_grantSession
• provider_request (CAIP-27) -> wallet_requestMethod or wallet_callMethod
• provider_getSession (CAIP-285) -> wallet_getSession or wallet_fetchSession
• provider_augment (CAIP-285) -> wallet_updateSession or wallet_extendSession
• provider_revoke (CAIP-285) -> wallet_deleteSession or wallet_revokeSession

[vandan]

we always envisioned _revoke lifecycle methods as allowing for both granular "de-escalation" of permissions and full revokations.

[pedrouid]

IDK because partial revocations seemed better executed with updateSession IMHO

From my POV, the word revoke sort of implies that action is irreversible therefore only applies to full revocations... I can be proven otherwise where prior work has used revoke for partial revocation

[vandan]

We're all in agreement on changing the prefix from provider_ to wallet_. Given that were headed towards making session IDs optional, naming-wise we were leaning toward the original "authorize" term to indicate what these lifecycle methods are managing though. ex:

• provider_authorize (CAIP-25) -> wallet_authorize
• provider_getSession (CAIP-285) -> wallet_getAuthorizations
• provider_revoke (CAIP-285) -> wallet_revokeAuthorization
• providerAuthorizationChanged (CAIP-285) -> wallet_authorizationChanged
• provider_request (CAIP-27) -> wallet_invokeMethod

We are still forming a perspective about:

1. Whether to support deltas or only "whole config" in these methods
2. Whether to split wallet_authorize into two methods (one for initial set of authorizations and another for additive ones)

[vandan]

We have an example of a method using the "revoke" term that targets a partial set of permissions with wallet_revokePermissions in our existing Wallet API.
They're in different domains, but we have also seen a number of examples of auth revokation methods that accept parameters to target specific revokations (aka de-escalation of authorizations). So there is an existing pattern for use of the "revoke" term in this way.

[vandan]

minor note that the suggested "wallet_authorize" method name could be more explicit as "wallet_requestAuthorization".

Generally it seems like the alternative pattern that's needed for CRUD operations that involve an intermediary (approver) are:

• Request (incremental or whole)
• Get (whole)
• Revoke (incremental or whole)
• Changed (notification of changes)

[pedrouid]

I've created a PR to update both CAIP-25 to wallet_createSession and CAIP-27 to wallet_requestMethod

[adonesky1]

Oh I was thinking we preferred wallet_invokeMethod for CAIP-27. IMO its better than wallet_requestMethod as the latter sounds (to me) like you're "requesting" the method rather than invoking or calling it.