Add more details on wallet structure to README by cy245 · Pull Request #43 · digitalcredentialsdev/CMWallet

cy245 · 2026-06-05T16:38:47Z

No description provided.

cy245 · 2026-06-05T16:40:21Z

@leecam @QZHelen please TAL - updated the readme to provide more insight into CMWallet. Let me know of any areas you'd like to update or add.

QZHelen · 2026-06-24T19:04:47Z

+* **Presentation Assembly**: The wallet extracts the requested claims, builds a cryptographically secure **Session Transcript** to bind the response to the specific connection, signs the response using the private key stored in secure hardware, packages the payload, and returns it to the calling verifier.
+
+### 2. Credential Issuance
+Handles credential issuance requests from issuers. When a user initiates getting a credential from an issuer by scanning a QR code or opening a link, the issuer can trigger a system intent that launches the credential creation and storage process:


Not exactly right - issuer calls the Android Credential Manager API to initiate the issuance call.

Still seems a bit off.. How about something like this:

Normally a user can trigger credential issuance in two ways:

Issuer initiated flow: the user triggers a request to issue a VDC from an issuer application or website. For example, an issuer.gov website may offer its users an option to "Add your passport to your wallet". The issuer calls the Credential Manager issuance API to make an OpenID4VCI Credential Offer request. To handle such requests a wallet must first integrate with Credential Manager to register its metadata. Credential Manager will display relevant options for a user to select. After the user selects a wallet option, the wallet application will be invoked and then the wallet can proceed with the steps needed to complete the issuance.

Wallet initiated flow: the user requests to add a VDC from their wallet application. For example, a wallet may offer a button to "Add your passport". In this case, the wallet maintains its supported issuer list and metadata. It does not need to integrate with the Android Credential Manager to complete this function.

CMWallet supports the issuer initiated flow, allowing arbitrary type of credentials in the SD-JWT VC or mdoc format.

Okay, updated as written with minimal changes.

QZHelen · 2026-06-24T19:06:09Z

+                                                                                                 │
+[Room DB] ◄── Save issued credential ◄── Hardware-backed attestation process ◄── Request credential from Issuer 
+```
+* **Issuer triggers intent**: The issuer triggers Android's `CREATE_CREDENTIAL` system intent, launching `CreateCredentialActivity`.


Let's just link to the Android DAC doc, or copy content over

Do you mean the below section or this line in particular? I think it's still useful to have text here - the DAC page can still be the maintained source of truth.

I added some more detailed suggestion in the comment above. We should update the sections Issuer triggers intent and Progress bottom to correctly reflect the issuance flow

I've gone ahead and removed the diagram as it may add more confusion given the wallet-initiated one doesn't use credman at all and could be perceived as simpler, though it doesn't scale well.

QZHelen · 2026-06-24T21:02:19Z

+└── matcher-rs/                          # Rust implementation of wasm matcher
+```
+
+### Detailed Directory Mapping


Do we need this part? Worry that it may become quickly outdated

This is intended to help users map each of the concepts covered to the directories in which they're implemented. Do we think the core files might change in the future? Even if new features are added the core files should likely remain the same - WDYT?

Fine with me either way; but I hope the structure above is good enough for most of the time.

Let's keep for now - I'll update as needed if things change.

QZHelen · 2026-06-26T00:24:13Z

+* **Presentation Assembly**: The wallet extracts the requested claims, builds a cryptographically secure **Session Transcript** to bind the response to the specific connection, signs the response using the private key stored in secure hardware, packages the payload, and returns it to the calling verifier.
+
+### 2. Credential Issuance
+Handles credential issuance requests from issuers. When a user initiates getting a credential from an issuer by scanning a QR code or opening a link, the issuer can trigger a system intent that launches the credential creation and storage process:


Still seems a bit off.. How about something like this:

Normally a user can trigger credential issuance in two ways:

Issuer initiated flow: the user triggers a request to issue a VDC from an issuer application or website. For example, an issuer.gov website may offer its users an option to "Add your passport to your wallet". The issuer calls the Credential Manager issuance API to make an OpenID4VCI Credential Offer request. To handle such requests a wallet must first integrate with Credential Manager to register its metadata. Credential Manager will display relevant options for a user to select. After the user selects a wallet option, the wallet application will be invoked and then the wallet can proceed with the steps needed to complete the issuance.

Wallet initiated flow: the user requests to add a VDC from their wallet application. For example, a wallet may offer a button to "Add your passport". In this case, the wallet maintains its supported issuer list and metadata. It does not need to integrate with the Android Credential Manager to complete this function.

CMWallet supports the issuer initiated flow, allowing arbitrary type of credentials in the SD-JWT VC or mdoc format.

QZHelen · 2026-06-26T19:15:21Z

+                                                                                                 │
+[Room DB] ◄── Save issued credential ◄── Hardware-backed attestation process ◄── Request credential from Issuer 
+```
+* **Issuer triggers intent**: The issuer triggers Android's `CREATE_CREDENTIAL` system intent, launching `CreateCredentialActivity`.


I added some more detailed suggestion in the comment above. We should update the sections Issuer triggers intent and Progress bottom to correctly reflect the issuance flow

QZHelen · 2026-06-26T20:21:44Z

+```
+* **Issuer triggers intent**: The issuer triggers Android's `CREATE_CREDENTIAL` system intent, launching `CreateCredentialActivity`.
+* **Progress bottom sheet**: The wallet displays a Compose bottom sheet showing a progress bar while it parses the Credential Offer.
+* **Key Generation and Attestation**: The wallet generates a secure cryptographic EC P-256 key pair in the phone's hardware-backed **Android KeyStore**. It creates a signed **DPoP Proof** and an **Android Keystore Key Attestation** to prove the key is tied to a genuine physical device.


CMWallet supports Android key attestation for credential binding keys. It provides a direct Android hardware backed key attestation and is the recommended key proof approach on Android.

Updated the bullet.

QZHelen · 2026-06-26T20:23:12Z

+## Directory & Module Guide
+
+```
+CMWallet/


Should also talk about the testdata folder that supports generating SD-JWT VC / mdoc for testing.

Added a section - can you help verify?

QZHelen · 2026-06-26T20:24:15Z

+└── matcher-rs/                          # Rust implementation of wasm matcher
+```
+
+### Detailed Directory Mapping


Fine with me either way; but I hope the structure above is good enough for most of the time.

QZHelen · 2026-07-08T06:12:07Z

I added some edits inline. Ptal and lmk if it looks good!

QZHelen · 2026-07-08T05:36:07Z

+* **Holder invocation**: If matching credential(s) are found, Android displays a credential selector
+  with the matched credentials to the user. The user selects the credential they want, which then
+  invokes the holder and launches the holder activity. CMWallet launches an additional
+  `BiometricPrompt` during invocation for additional user consent.


Replace user consent with user authentication

cy245 · 2026-07-08T18:20:11Z

I added some edits inline. Ptal and lmk if it looks good!

I'm good with these changes. Feel free to approve/merge when ready.

Add more details on wallet structure to README

e032491

QZHelen reviewed Jun 24, 2026

View reviewed changes

Comment thread README.md Outdated

QZHelen reviewed Jun 24, 2026

View reviewed changes

cy245 added 2 commits June 25, 2026 14:06

Format document

e758072

Apply reviewer feedback

1456b6f

QZHelen reviewed Jun 26, 2026

View reviewed changes

cy245 and others added 3 commits July 7, 2026 17:13

Made updates per feedback

bfce411

Minor formatting

f9de265

Clarify presentation and issuance flows in README.md

8ab8ea5

QZHelen reviewed Jul 8, 2026

View reviewed changes

minor text update

0011d9d

QZHelen merged commit 3ce1f94 into digitalcredentialsdev:main Jul 8, 2026
1 check passed

Uh oh!

Conversation

cy245 commented Jun 5, 2026

Uh oh!

cy245 commented Jun 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

QZHelen commented Jul 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cy245 commented Jul 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants