A common interface for decentralized applications and cryptocurrency wallets (or other key management applications described in future CASA namespaces and CAIPs) to communicate about and pass Verifiable Credentials and Verifiable Presentations is needed for the chain-agnostic world to interact with emerging decentralized/portable data applications. Many [elsewhere mandatory] aspects of the verifiable credential and decentralized identifier stacks are left out of scope to be handled in future CAIPs as needed, storage and encryption being two notable examples.
This specification adds new methods to the multi-provider JSON-RPC for storing,
creating, selectively disclosing and proving control of offchain- and onchain
credentials under a new wallet_creds_ prefix.
After a dapp has requested and a wallet has declared basic verifiable credentials capabilities in the CAIP-25 feature-discovery step, dapps can assume the wallet will be able to support all the methods defined below. Note that many of these calls should be routable to services, other software, or even other dapps, without leaking information about the wallet or architecture to the calling dapp.
This CAIP describes a few core RPC methods that combine to act as a wallet-side Credential Provider (CP) to support Verifiable Credentials (VCs) storage, issuance, proof-of-control, and even (with some extensions) selective disclosure or advancing proofing of those credentials.
VCs are self-certifiable attestations from an issuer about the subject of the VC. The holder of a VC can directly consent to disclosing information from those VCs and, in combination with other tokens or cryptographic forms of evidence, substantiate their context or the relationship between holder and subject. See the VC spec for more context. To facilitate developer experience and progress towards end-to-end interoperability, this CAIP limits its scope to a few supported proof types and focuses on a limited subset of today's VC systems. This CAIP is important for use cases such as privacy-preserving compliance, sign-in, sign-up, and decentralized reputation-based authorization.
Web3 applications like DAOs, Defi, NFT market places etc. need verifiable offchain and onchain reputation to enable certain features for their end users. Web3 is missing a coherent method for requesting identity assertions from their users, e.g. for sign-in and sign-up. The majority of Web3 projects are using an approach where they cryptographically bind a signature produced by a single-context (and single-chain) wallet to the identity assertion; in the EVM, for example, these approaches usually rely on either eth.personal.sign or EIP-712. The identity assertion becomes self-certifiable with this approach, but tightly bound to the Ethereum address as the only identifier. To improve privacy it is important to introduce a mechanism that allows people to selectively disclose the linkage between another identifier (such as a chain-agnostic or off-chain DID) and their blockchain account address.
This can be done through VCs and DIDs. This CAIP introduces new JSON-RPC methods that are needed to build decentralized reputation for offchain and onchain uses alike.
The identifiers by which issuers and holders and their key material are dereferenced for verification and binding purposes are out of scope of this specification, but complemented nicely by DID-based approaches such as those established in the EVM space by [EIP-2844][] or the cross-chain blockchain-based approach indexed by the did pkh multicodec. Implementing verifiable credential exchange without DIDs may lead to a closed and limited system with limited interoperability or exportability; systems that can extend and federate over time are encouraged to build in flexibility at both the credential format level as well as the decentralized identifier level.
Three new JSON-RPC methods are specified under the new wallet_creds_* prefix.
This section provides guidance on recommended LD-Proof Suites and IANA JWS algorithm support of embedded and external proofs for VCs. The abbreviations for common VC formats in production today are taken from the DIF Claim Format registry of the Presentation Exchange meta-protocol specification governed by the Decentralized Identity Foundation, while the Verifiable Credentials profile defining their proof formats are specified in the VC spec itself.
Credential issuance systems MUST support the following LD-Proof types for embedded proofs (i.e. VC-LDP):
EthereumEip712Signature2021JsonWebSignature2020, only
Ed25519 and secp256k1Credential issuance systems are RECOMMENDED to support the following LD-Proof types for wide support of VC formats with embedded proofs (i.e. VC-LDP):
CPs SHOULD support the following IANA JWS algorithms for external proofs (i.e. VC-JWT):
A helpful test suite for conformance-testing VC-JWT signing can be found at JWS-test-suite.
VCs that can be used with this specification MUST be valid JSON-LD as defined in the VC spec. VCs and VPs MUST use either the proofs recommended by Embedded Proofs or External Proofs above to conform to this specification; implementations are RECOMMENDED to limit themselves to algorithms and key types corresponding to registered claim formats in the DIF Claim Format registry if they are expecting reasonable interoperability in the near term, and to carefully construct their presentation_definition object accordingly.
Stores the given VC in the CP.
wallet_creds_store
vc - A Verifiable Credential.error - OPTIONAL. If vc was malformed or does not comply with the
Verifiable Credentials Profile defined in this specification. Note that some
wallets will call wallet_creds_verify locally or remotely and pass back an
error message received thereby, depending on security context.
wallet_creds_metadata)Verifies the proof section of a single verifiable credential after dereferencing
its issuer property for key material. Note that in an application<>wallet
connection, the application calls the wallet for the wallet to either perform
verification locally or remotely; in either case, the application will await
asynchronously for a success or error code, regardless of how the wallet
verifies the passed credential. Wallets that cannot return appropriate error
codes back MUST NOT authorize apps to call this method as undefined behavior may
occur.
wallet_creds_verify
vc - A Verifiable Credential.error - OPTIONAL. If vc was malformed or does not comply with the
Verifiable Credentials Profile defined in this specification.Called by the wallet to the application, providing the parameters needed for a credential issuance and expecting back a verifiable credential OR an error. The parameters are formatted as a credential_application object as specified in the Credential Manifest specification.
wallet_creds_issue
credential_application - REQUIRED. This can vary from the full contents of
the payload of the to-be-issued credential to a mere consent event per
use-case, but in either case MUST be formated as a valid
credential_application object as specified in the Credential Manifest
specification.preferred_proofs - OPTIONAL. An ordered array (from most to least
preferred) of preferred proof formats and types for the VC to be issued. Each
array item is an object with two properties, format and type. format
indicates the preferred proof type, which is either jwt for (External
Proofs) or ldp for (Embedded Proofs). The type refers to proof type of the
VC (see Verifiable Credentials Proofs for a
list of valid combinations). If the wallet does not support any of the
preferred proofs, the wallet can select a format and type from the list
defined in Verifiable Credentials Proofs as
a fallback.vc - OPTIONAL. Present if the call was successful. A Verifiable Credential
that was issued to the CP by the application.error - OPTIONAL. If payload was malformed, or does not comply with the
Verifiable Credentials Profile defined in this specification.
credential_application or payload constructionThe application calls the wallet to request verifiable claims from the CP. For the query, we will use the DIF Presentation Exchange data model. Optionally, holder binding can also be requested.
wallet_creds_present
presentation_definition - A presentation_definition object as defined in
the Presentation Exchange specification; among other parameters such as
claim format, this can also include constraints about selective disclosure, LD
framing, and optional holder binding requirements.domain - OPTIONAL. If holder binding was requested, this parameter is mandatory.challenge - OPTIONAL. If holder binding was requested, this parameter is mandatory.vp - OPTIONAL. Present if the call was successful. It contains a Verifiable
Presentation (VP) structured as a JSON object that contains the requested VCs
from the CP.error - OPTIONAL. Present if presentation_definition was malformed, does
not comply with the Verifiable Credentials Profile defined in this
specification.Called by the application to fetch a configuration object describing signing and verification capabilities of the wallet. This method is an optional way for CAIP-169 supporting wallets to signal signing and verifying capabilities in addition to those necessary for the blockchain/VM-specific accounts and methods already exposed; it is required for interoperability with OIDC-based protocols, and its absence can be interpreted as an absence of interoperability with protocols requiring it.
The formatting and values of the metadata object are borrowed from the [OIDC4VP][] specification, which in references the DIF Claim Format registry for the names of objects and IANA JOSE Registry for the exact, case-sensitive abbreviations contained therein. Note that no other values from a full OAuth2 Authorization Server metadata need to be present, and they will be ignored if included.
NOTE: alg value none SHOULD NOT be accepted.
wallet_creds_metadata
URL_accepted - OPTIONAL. Boolean, default to false if not present. If true,
metadata object MAY be passed as an HTTPS URL OR as an object; otherwise, MUST
be passed as a JSON object.metadata_object - OPTIONAL. See [OIDC4VP][] section "Authorization Server
Metadata" for properties.error - OPTIONAL.
wallet_creds_metadata)The VC Data Model defines a Verifiable Presentation but does not provide detail on how to express the constraints that a relying party can impose on a presentation. The Presentation Exchange Data Model defines a definition and submission format for among other things, verifiable presentations.
The Universal Wallet Interop Spec describes how to use concrete protocols such as Wallet Connect and WACI Presentation Exchange with DID Comm Messaging.
In cases where a holder is directly connected to a verifier over a secure transport, encryption and messaging related standards such as DIDComm are not required, however interoperable data models for expressing presentation requirements and submissions are still needed to support interoperability with existing standards.
This proposal defines a set of API extensions that would enable web3 wallet providers to offer wallet and credential interactions to web origins that already support web3 wallet providers.
This functionality is similar to the interfaces supported by the credential handler api, which does not support the Presentation Exchange Data Model specification but does offer more flexible support for Linked Data verifiable credential formats and a rich interface for wallet selection via the Credential Handler API (CHAPI). Interoperability with other set of interfaces may require extensions or breaking changes to this specification, and is out of scope for now.
TBD
See:
User consent must be obtained prior to accessing wallet APIs. One way of achieving this is with a strong UX around CAIP-25 authorization to ensure meaningful user consent to access levels per account, per method/wallet capability (including those specified in this specification), and per additional resource.
The relying party MUST ensure that: the challenge required by the verifiable presentation is sufficiently random; that it is used only once, tracked against some form of session object (see CAIP-170 and CAIP-171), etc; or that it is some form of expiring verifiable credential encoded as a string. Man-in-the-middle protection and other security assumptions fall on the relying party (i.e. the calling application) to secure.
Appropriate domain-binding for web/http-based dapp-wallet connections is assumed and out of scope for this specification. Other CAIPs may be forthcoming for hardening this assumption, or may rely on the domain-binding enforced by a preceding [CAIP-122][] flow.
Similarly, holder binding (e.g. binding the current wallet controller to the wallet controller at time of credential issuance) is out of scope of this specification but assumed by it. Where no holder binding beyond wallet control is enforced, the submission details can be tampered with and should be considered unsecured. Some useful forms of holder binding can be provided by: wallet-level strong authentication; supplemental liveness or multi-factor authentication mechanisms; complex holder-binding mechanisms registered as extensions to the [VC Extension Registry][]; future CAIPs; etc.
Specifications (Dependencies)
Specifications (Optional Dependencies and Prior Art)
Prior Art and Reference Implementations
Copyright and related rights waived via CC0.