Similar to Sign in with Ethereum (SIWE), this is a chain-agnostic proposal for connecting to and signing in with one interaction.
This CAIP defines a JSON-RPC method to authenticate wallet ownership/control of one or more blockchain account(s), on one or more specific chains.
This proposal provides a simpler user experience by bundling two wallet requests into a single method to provide wallet authentication when exposing blockchain accounts with a cryptographic signature
Prior this standard Wallets were required to establish a JSON-RPC connection with an application (Dapp) to expose blockchain accounts but this required a secondary request to verify ownership of each account to return a cryptographic signature.
There are challenges regarding the flexibility of what can be signed or not without prior knowledge of the blockchain accounts but with the adoption of standards like SIWx (CAIP-122) we have the ability to define specific parameters that can be signed securely without the accounts being exposed beforehand.
This will accelerate wallet adoption by social media applications which do not require persistent sessions and only need a single cryptographic signature to verify ownership of blockchain accounts.
This JSON-RPC method can be requested to a wallet provider without prior knowledge of the blockchain accounts.
The requester will provide parameters required by CAIP-122 plus a CACAO header type as specified by CAIP-74
The responder will return zero, one, or more signed CACAO(s) with a header type and payload matching the requested parameters.
The application would interface with a provider to make request as follows:
The JSON-RPC method is labelled as wallet_authenticate and expects the following parameters:
chainIds to identify one or more networks to authorize.dnsauthority that is requesting the signing.date-time that indicates the issuance time.date-time that indicates when the signed authentication message is no longer valid.date-time that indicates when the signed authentication message starts being valid.\n.\n.signatureTypesThe wallet will prompt the user with a dedicated UI to display the app requesting the authentication and allow the user to select which blockchain account to sign with.
If approved, the wallet will return a list of signed, valid CACAOs for each account authorized on the networks requested by the chains property.
All payload parameters MUST match the same parameters as the ones provided in the request and the following will be added:
type in request)Request will fail if rejected by the user or if parameters fail validation.
The following Error responses MUST be used:
The wallet SHOULD ignore all unsupported chains and SHOULD NOT auto reject the request if there are supported chains to sign without explicit user rejection.
This standard provides both benefits to users and developers by compiling two widely adopted patterns into a single request: connecting a wallet and signing an authentication message.
Users have the ability to quickly authenticate into applications without establishing a persistent session before they have decided to actually expose a two-way communication channel to sign more messages and/or transactions.
Developers have the ability to verify ownership of users' blockchain accounts similarly to how other authentication standards like OAuth and OIDC using also a more familiar interface that is commonly found in many social applications today.
This also incentives more applications to prevent impersonation by verifying ownership of blockchain accounts upfront without needing to trust the wallet provider interface that optimistically exposes account on connection.
This interface can be used with multiple accounts by including in the response an array of signed CACAOs for each address.
Here is an example request and response exchange with wallet_authenticate method with single chain request:
Example request and response with multiple chains
In order to provide the user guarantees of the origin for the request the wallet MUST provide domain binding by verifying the origin matches the domain parameter as described in CAIP-122 description under "Verify domain binding"
Users must be prompted explicitly to approve wallet_authenticate requests as these not only verify ownership of a specific blockchain account as specified in the iss param but also they are exposing it to the application which will be able to index and explore blockchain history corresponding to the blockchain account used for signing.
CACAO versioning is included as a parameter for this request to allow backwards-compatibility for future changes in CAIP-74 standard.
Copyright and related rights waived via CC0.