SDP-1637 embedded wallets docs #2187
Conversation
There was a problem hiding this comment.
Pull request overview
This pull request adds comprehensive documentation for the Embedded Wallets feature in the Stellar Disbursement Platform (SDP). Embedded Wallets enable receivers to receive disbursements using passkey-secured smart contract wallets without needing to download a separate wallet application.
Changes:
- Added new embedded-wallets.mdx documentation explaining the feature, its benefits, and step-by-step usage guide
- Added Embedded Wallets configuration section to advanced-configuration.mdx with backend, TSS, and frontend setup instructions
- Added screenshot image (SDP48.png) showing the verification prompt interface
- Fixed list formatting in the Distribution Account configuration section
Reviewed changes
Copilot reviewed 2 out of 5 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| embedded-wallets.mdx | New comprehensive guide covering embedded wallets introduction, passkey technology, workflow, prerequisites, and usage steps |
| advanced-configration.mdx | Added embedded wallets configuration section with environment variables for backend, TSS, and frontend; fixed list formatting |
| SDP48.png | New screenshot image showing the verification interface for embedded wallets |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/platforms/stellar-disbursement-platform/admin-guide/embedded-wallets.mdx
Outdated
Show resolved
Hide resolved
docs/platforms/stellar-disbursement-platform/admin-guide/advanced-configration.mdx
Outdated
Show resolved
Hide resolved
docs/platforms/stellar-disbursement-platform/admin-guide/advanced-configration.mdx
Show resolved
Hide resolved
docs/platforms/stellar-disbursement-platform/admin-guide/embedded-wallets.mdx
Show resolved
Hide resolved
|
Preview is available here: |
1 similar comment
|
Preview is available here: |
| 1. Make sure the SEP-10 account exists on the Stellar network by funding it | ||
| 2. Configure the backend with the RPC endpoint | ||
| 3. Configure TSS with the same RPC endpoint | ||
| 4. Enable RPC features in the frontend dashboard |
There was a problem hiding this comment.
We also need to enable the embedded wallet manually in the UI
| The Embedded Wallet flow consists of several steps that happen automatically: | ||
|
|
||
| 1. **Disbursement Creation**: An administrator creates a disbursement and selects "Embedded Wallet" as the wallet provider | ||
| 2. **Invitation Sent**: The SDP sends an invitation link to each receiver via SMS or email |
There was a problem hiding this comment.
We should note that the link is unique per user. If the link is leaked and there is no verification, an attacker can steal funds by creating the victim's wallet.
|
|
||
| - The frontend uses **WebAuthn** to authenticate the receiver with their biometric or device PIN | ||
| - The backend verifies the authentication using the stored public key | ||
| - A **SEP-45 JWT session token** is generated to prove the receiver controls the wallet |
There was a problem hiding this comment.
There are actually two JWTs used by the wallet; it looks like you're describing the wallet auth JWT that's issued during wallet creation and login. It's used to access SDP API's like fetching the user's profile or accessing RPC.
The SEP-45 JWT is only issued and used by the SEP-24 flow.
|
|
||
| 2. **Frontend HTTPS Requirement**: The frontend dashboard **must** be served over HTTPS for passkeys to work. WebAuthn requires a secure context and will not function over plain HTTP. | ||
|
|
||
| 3. **Network Selection**: Ensure you've deployed the embedded wallet contract to your target network (testnet or mainnet) and have the correct WASM hash configured. |
There was a problem hiding this comment.
Deploy the SEP-45 contract and the embedded wallet Wasm.
| - **Registration Contact Type**: Choose how receivers will be contacted (Email or SMS) | ||
| - **Wallet Provider**: Select "Embedded Wallet" from the dropdown | ||
| - **Asset**: Choose the asset to disburse (e.g., USDC, XLM) | ||
| - **Verification Type**: Select what information receivers must verify (e.g., PIN, date of birth) |
There was a problem hiding this comment.
Maybe we can also say that there's a no verification option available to embedded wallets only and warn that it should only be used for small amounts.
|
|
||
| The verification process uses the SDP's native SEP-24 implementation. The receiver authenticates with a SEP-24 JWT token that's generated during the passkey authentication flow. | ||
|
|
||
| For background on SEP-45 (contract-account web authentication), see the [SEP-45 guide](https://developers.stellar.org/docs/platforms/anchor-platform/sep-guide/sep45). |
There was a problem hiding this comment.
I would link to the protocol itself rather than the Anchor Platform's explaination.
|
|
||
| Embedded Wallets allow receivers to receive disbursements without needing to download or manage a separate wallet application. When you create a disbursement with Embedded Wallets as the target wallet provider, the SDP automatically creates a lightweight, passkey-secured smart contract wallet for each receiver. | ||
|
|
||
| ### Why Use Embedded Wallets? |
There was a problem hiding this comment.
We should also call out the limitations, which include not being able to send to exchanges and no integration with any ramps.
|
|
||
| Before using Embedded Wallets, ensure your SDP instance is properly configured: | ||
|
|
||
| 1. **Backend Configuration**: Embedded Wallets require specific environment variables to be set. See the [Embedded Wallets Configuration](#configuration) section in the Advanced Configuration guide. |
There was a problem hiding this comment.
This link does not redirect, should be ./advanced-configration#embedded-wallets-configuration ?
No description provided.