Skip to content

Strawman of a CAIP-25 split into required/optional with session properties attached and verbose response #187

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bumblefudge merged 9 commits into from
Dec 7, 2022
Merged

Strawman of a CAIP-25 split into required/optional with session properties attached and verbose response #187

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b99b95f
alternate extensions model
Nov 22, 2022
c5224d4
to rename sessionIdentifer in res
Nov 24, 2022
c0c6769
option/req extended
Nov 24, 2022
625c6b1
typo - caip-170 link
Nov 24, 2022
6ddf56a
to fix indentation
Nov 29, 2022
b93bc01
change requested session param in example
Dec 5, 2022
1771c97
Update CAIPs/caip-25.md
Dec 7, 2022
a3e3df9
editorial changes discussed on today's call
Dec 7, 2022
1fff030
Merge branch 'master' into caip25-options-not-extensions
Dec 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 122 additions & 28 deletions CAIPs/caip-25.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,66 +43,145 @@ a new session, whether due to user input, security policy, or session expiry
reasons, it can simply generate a new session identifier to signal this event to
the calling provider.

The application interfaces with a provider to populate a session with a base
state describing authorized chains, methods, event, and accounts. This
negotation takes place by sending the application's REQUIRED and REQUESTED
properties of the session. If any requirements are not met, a failure response
expressive of one or more specific failure states will be sent (see below).
Conversely, a succesful response will contain all the required properties *and
the provider's choice of the optional properties* expressed as a unified set of
parameters.

### Request

The application would interface with a provider to authorize that provider with a
given set of parameters by calling the following JSON-RPC request

```
Example:

```jsonc
{
"id": 1,
"jsonrpc": "2.0",
"method": "provider_authorization",
"params": {
"eip155": {
"chains": ["eip155:1"],
"methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "personal_sign"]
"events": ["accountsChanged", "chainChanged"]
},
"cosmos": {
...
}
"id": 1,
"jsonrpc": "2.0",
"method": "provider_authorization",
"params": {
"requiredNamespaces": {
"eip155": {
"chains": ["eip155:1", "eip155:137"],
"methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"],
"events": ["accountsChanged", "chainChanged"]
},
"eip155:10": {
"methods": ["get_balance"],
"events": ["accountsChanged", "chainChanged"]
},
"cosmos": {
...
}
},

"optionalNamespaces":{
"eip155:42161": {
"methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"],
"events": ["accountsChanged", "chainChanged"]
},
"sessionProperties": {
"expiry": "2022-12-24T17:07:31+00:00",
"caip154-mandatory": "true"
}
}
}
```

The JSON-RPC method is labelled as `provider_authorization` and expects one or
more objects each named after the pertinent ChainAgnostic namespace and each
containing with three parameters:
- chains - array of [CAIP-2][] compliant chainId's
The JSON-RPC method is labelled as `provider_authorization` and both the
"requiredNamespaces" and "optionalNamespaces" arrays are populated with
`namespace` objects each named after the scope of authorization:
1. EITHER an entire ChainAgnostic [namespace][]
2. OR a specific [CAIP-2][] in that namespace.

Each `namespace` object contains the following parameters:
- chains - array of [CAIP-2][]-compliant `chainId`'s. This parameter MAY be
omitted if a single-chain scope is already declared in the index of the object.
- methods - array of JSON-RPC methods expected to be used during the session
- events - array of JSON-RPC message/events expected to be emitted during the
session

The `requiredNamespaces` array MUST contain 1 or more of these objects, and MUST
be present; the `optionalNamespaces` array MUST contain 1 or more of them, if
present.

A third object is the `sessionProperties` object, all of whose properties MUST
be in the interpreted as optional, since requesting applications cannot mandate
session variables to providers. Because they are optional, providers MAY respond
with all of the requested properties, or a subset of the session properties, or no
`sessionProperties` object at all; they MAY even replace the values of the
optional session properties with their own values. The `sessionProperties`
object MUST contain 1 or more properties if present.

Requesting applications are expected to track all of these returned properties in
the session object identified by the `sessionId`. All properties and their values
MUST conform to definitions in [CAIP-170][], and MUST be ignored (rather than
tracked) if they do not.

### Response

The wallet can respond to this method with either a success result or an error message.

#### Success

The response MUST be a success result when the user approved accounts matching
the requested chains to be exposed and the requested methods to be used.
The succesfull reslt contains one mandatory string (keyed as `sessionId` with a value
conformant to [CAIP-171][]) and two session objects, both mandatory and non-empty.

The first is called `sessionNamespaces` and contains 1 or more namespace objects.
* All required namespaces and all, none, or some of the optional namespaces (at the
discretion of the provider) MUST be included if successful.
* As in the request, each namespace object MUST contain `methods` and `events` objects,
and a `chains` object if a specific chain is not specified in the object's index.
* Unlike the request, each namespace object MUST also contain an `accounts` array,
containing 0 or more [CAIP-10][] conformant accounts authorized for the session and valid
in the namespace and chain(s) authorized by the object they are in. Additional constraints
on the accounts authorized for a given session MAY be specified in the corresponding
[namespaces][] specification.

The response MUST include a key `sessionIdentifier` the value of which is a
`SessionIdentifier` as defined in [caip-171][].
A `sessionProperties` object MAY also be present, and its contents MAY correspond to the
properties requested in the response or not (at the discretion of the provider) but MUST
conform to the properties names and value constraints described in [CAIP-170][]; any other
MUST be dropped by the requester.

An example of a successful response should match the following format:
An example of a successful response follows:

```jsonc
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"sessionIdentifier": "0xdeadbeef",
"accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"]
"sessionId": "0xdeadbeef",
"sessionNamespaces": {
"eip155": {
"chains": ["eip155:1", "eip155:137"],
"methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "eth_sign", "personal_sign"]
"events": ["accountsChanged", "chainChanged"],
"accounts": ["eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb", "eip155:137:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb"]
},
"eip155:10": {
"methods": ["get_balance"],
"events": ["accountsChanged", "chainChanged"],
"accounts:" []
},
"eip155:42161": {
"methods": ["personal_sign"],
"events": ["accountsChanged", "chainChanged"],
"accounts":["eip155:42161:0x0910e12C68d02B561a34569E1367c9AAb42bd810"]
"cosmos": {
...
},
"sessionProperties": {
"expiry": "2022-11-31T17:07:31+00:00"
}
}
}
}
```

The accounts returned as a result should match the requested `chainId`s and
should be an array of CAIP-10 compliant `accountId`s.

#### Failure States

The response MUST NOT be a success result when the user disapproves the accounts
Expand Down Expand Up @@ -142,6 +221,18 @@ The valid error messages codes are the following:
* When wallet evaluates requested events to not be supported
* code = 5102
* message = "Requested events are not supported"
* When a badly-formed request includes a `chainId` mismatched to scope
* code = 5103
* message = "Scope/chain mismatch"
* When a badly-formed request defines one `chainId` two ways
* code = 5104
* message = "ChainId defined in two different scopes"
* Invalid Session Properties Object
* code = 5200
* message = "Invalid Session Properties requested"
* Required Session Properties
* code = 5201
* message = "Session Properties can only be optional"

## Changelog

Expand All @@ -162,6 +253,9 @@ The valid error messages codes are the following:
[CAIP-25]: https://chainagnostic.org/CAIPs/caip-25
[CAIP-75]: https://chainagnostic.org/CAIPs/caip-75
[CAIP-171]: https://chainagnostic.org/CAIPs/caip-171
[namespaces]: https://namespaces.chainagnostic.org
[RFC3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6
[CAIP-170]: https://chainagnostic.org/CAIPs/caip-170

## Copyright

Expand Down