|
| 1 | +--- |
| 2 | +title: Embedded Wallets |
| 3 | +description: Learn how to use Embedded Wallets to enable receivers without existing Stellar wallets to receive disbursements using passkey authentication. |
| 4 | +keywords: [embedded wallets, passkeys, WebAuthn, smart contracts, disbursements] |
| 5 | +sidebar_position: 50 |
| 6 | +--- |
| 7 | + |
| 8 | +# Embedded Wallets |
| 9 | + |
| 10 | +## Introduction |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +### Why Use Embedded Wallets? |
| 15 | + |
| 16 | +Embedded Wallets significantly reduce friction for receivers who don't have an existing Stellar wallet: |
| 17 | + |
| 18 | +- **No App Download Required**: Receivers don't need to download a separate wallet application |
| 19 | +- **Passwordless Authentication**: Uses passkeys (biometric or device-based authentication) instead of passwords |
| 20 | +- **Phishing-Resistant**: Built on WebAuthn standards that prevent credential theft |
| 21 | +- **Simple User Experience**: Receivers can claim their funds with just a few clicks |
| 22 | + |
| 23 | +### Limitations |
| 24 | + |
| 25 | +Before enabling Embedded Wallets, note the current limitations: |
| 26 | + |
| 27 | +- **No exchange transfers**: Embedded wallets cannot send directly to exchanges. |
| 28 | +- **No built-in offramp**: Offramping must be handled out-of-band (for example, a direct transfer to a user-provided address). |
| 29 | +- **Single wallet per receiver**: Each receiver can create only one embedded wallet |
| 30 | + |
| 31 | +### Key Concepts |
| 32 | + |
| 33 | +**Smart Contract Wallets**: Embedded Wallets are Stellar smart contract accounts that are deployed on-chain when a receiver creates their passkey. These contracts are controlled by the receiver's passkey credential. |
| 34 | + |
| 35 | +**Passkeys**: A modern authentication method that replaces passwords with cryptographic keys stored securely on the user's device, unlocked with biometrics (fingerprint, Face ID, etc.) or device PIN. |
| 36 | + |
| 37 | +**SEP-45**: A Stellar web authentication protocol for contract accounts (`C...`) that lets wallets prove control of a smart contract wallet and obtain a JWT session token from a service. The SDP uses SEP-45 during SEP-24 flows to verify that receivers control their embedded wallets. |
| 38 | + |
| 39 | +--- |
| 40 | + |
| 41 | +## What are Passkeys? |
| 42 | + |
| 43 | +Passkeys are a replacement for passwords that provide stronger security and a better user experience. Instead of remembering and typing a password, users authenticate with biometrics (like fingerprint or facial recognition) or their device's PIN/pattern. |
| 44 | + |
| 45 | +### How Passkeys Work |
| 46 | + |
| 47 | +When a receiver creates an embedded wallet: |
| 48 | + |
| 49 | +1. The browser or device generates a **cryptographic key pair** (public key and private key) |
| 50 | +2. The **private key** is stored securely on the receiver's device and never leaves it |
| 51 | +3. The **public key** is sent to the SDP and used to create the smart contract wallet |
| 52 | +4. When signing in later, the receiver uses biometrics to unlock their private key |
| 53 | + |
| 54 | +### Why Passkeys are More Secure |
| 55 | + |
| 56 | +**Phishing-Resistant**: Unlike passwords, passkeys are cryptographically bound to your domain. Even if a receiver visits a fake website, their passkey won't work there. |
| 57 | + |
| 58 | +**Automatically Unique**: Each passkey is unique per service. There's no risk of password reuse across sites. |
| 59 | + |
| 60 | +**Breach-Resistant**: The SDP only stores public keys. Even if the database is compromised, attackers cannot use public keys to authenticate. |
| 61 | + |
| 62 | +**No Weak Passwords**: Users can't create weak or easily-guessed credentials. All passkeys use strong cryptography. |
| 63 | + |
| 64 | +:::info Learn More About Passkeys |
| 65 | + |
| 66 | +For more details about passkey technology, visit [passkeys.dev](https://passkeys.dev/docs/intro/what-are-passkeys/) or read about the [WebAuthn specification](https://www.w3.org/TR/webauthn/). |
| 67 | + |
| 68 | +::: |
| 69 | + |
| 70 | +--- |
| 71 | + |
| 72 | +## How It Works |
| 73 | + |
| 74 | +The Embedded Wallet flow includes the following steps: |
| 75 | + |
| 76 | +1. **Disbursement Creation**: An administrator creates a disbursement and selects "Embedded Wallet" as the wallet provider |
| 77 | +2. **Invitation Sent**: The SDP sends an invitation link to each receiver via SMS or email. The link is unique per receiver. |
| 78 | +3. **Passkey Creation**: The receiver clicks the link and creates a passkey using their device's biometric authentication |
| 79 | +4. **Wallet Deployment**: The SDP deploys a smart contract wallet on the Stellar network, controlled by the receiver's passkey |
| 80 | +5. **Verification**: The receiver completes identity verification (e.g., entering an OTP or date of birth) |
| 81 | +6. **Payment Transfer**: Once verified, the SDP automatically transfers the disbursement funds to the receiver's contract wallet |
| 82 | + |
| 83 | +:::danger |
| 84 | + |
| 85 | +Each link is unique per receiver. Treat it as sensitive: if a link is leaked and you have **no verification** enabled, an attacker could create the receiver’s wallet and claim the funds. Skipping verification should only be done in low-risk scenarios and with small disbursement amounts. |
| 86 | + |
| 87 | +::: |
| 88 | + |
| 89 | +### Behind the Scenes |
| 90 | + |
| 91 | +When a receiver logs in with their passkey, several things happen: |
| 92 | + |
| 93 | +- The frontend uses **WebAuthn** to authenticate the receiver with their biometric or device PIN |
| 94 | +- The backend verifies the authentication using the stored public key |
| 95 | +- A **wallet-auth JWT** is generated for SDP APIs (e.g., profile and RPC access) |
| 96 | +- The SDP **sponsors transactions** on behalf of the receiver, covering all network fees |
| 97 | +- Payments are made using **Stellar Asset Contract (SAC)** transfers to the smart contract address |
| 98 | + |
| 99 | +--- |
| 100 | + |
| 101 | +## Prerequisites |
| 102 | + |
| 103 | +Before using Embedded Wallets, ensure your SDP instance is properly configured: |
| 104 | + |
| 105 | +1. **Backend Configuration**: Embedded Wallets require specific environment variables to be set. See the [Embedded Wallets Configuration](./advanced-configuration#embedded-wallets-configuration) section in the Advanced Configuration guide. |
| 106 | + |
| 107 | +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. |
| 108 | + |
| 109 | +3. **Network Selection**: Deploy the SEP-45 contract and the embedded wallet Wasm. |
| 110 | + |
| 111 | +For detailed configuration instructions, see the [Embedded Wallets Configuration](./advanced-configuration#embedded-wallets-configuration) section. |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +## Using Embedded Wallets |
| 116 | + |
| 117 | +### Step 1: Create a Disbursement with Embedded Wallet |
| 118 | + |
| 119 | +When creating a new disbursement, select **"Embedded Wallet"** as the wallet provider in the disbursement details form. |
| 120 | + |
| 121 | + |
| 122 | + |
| 123 | +**What to configure:** |
| 124 | + |
| 125 | +- **Registration Contact Type**: Choose how receivers will be contacted (Email or SMS) |
| 126 | +- **Wallet Provider**: Select "Embedded Wallet" from the dropdown |
| 127 | +- **Asset**: Choose the asset to disburse (e.g., USDC, XLM) |
| 128 | +- **Verification Type**: Select what information receivers must verify (e.g., PIN, date of birth) |
| 129 | + |
| 130 | +:::note |
| 131 | + |
| 132 | +There is also a "None" option, but using it is only recommended for low-risk scenarios due to security concerns (e.g. disbursing small amounts). |
| 133 | + |
| 134 | +::: |
| 135 | + |
| 136 | +Once you've uploaded your disbursement CSV file and submitted the disbursement, the SDP will begin sending invitations to all receivers in the list. |
| 137 | + |
| 138 | +--- |
| 139 | + |
| 140 | +### Step 2: Receiver Creates Passkey |
| 141 | + |
| 142 | +Receivers will receive an invitation message (via SMS or email) with a secure link to create their embedded wallet. The link format looks like this: |
| 143 | + |
| 144 | +```j |
| 145 | +https://your-tenant.sdp.stellar.org/wallet?asset=native&token=c09bd254-b77a-4685-bc18-377231484267&signature=26b48d7ce... |
| 146 | +``` |
| 147 | + |
| 148 | +:::danger Reminder |
| 149 | + |
| 150 | +Each link is unique per receiver. Treat it as sensitive: if a link is leaked and you have **no verification** enabled, an attacker could create the receiver’s wallet and claim the funds. Skipping verification should only be done in low-risk scenarios and with small disbursement amounts. |
| 151 | + |
| 152 | +We also recommend enabling verification because it requires users to authenticate via SEP-45 before receiving funds. This confirms their passkey works correctly. This helps avoid cases where accounts are created and funds disbursed, but users are prevented from accessing the wallet due to passkey issues that would have been caught during verification. |
| 153 | + |
| 154 | +::: |
| 155 | + |
| 156 | +When the receiver clicks the link, they'll see a page inviting them to create their wallet account: |
| 157 | + |
| 158 | + |
| 159 | + |
| 160 | +**The passkey creation process:** |
| 161 | + |
| 162 | +1. The receiver clicks **"Log in with passkey"** |
| 163 | +2. Their browser or device prompts them to create a passkey (first-time users) or authenticate with an existing passkey (returning users) |
| 164 | +3. For new users, they'll scan their fingerprint, face, or enter their device PIN |
| 165 | +4. The browser generates a cryptographic key pair securely on the device |
| 166 | + |
| 167 | +**What happens behind the scenes:** |
| 168 | + |
| 169 | +- The frontend calls `POST /embedded-wallets/passkey/registration/start` with the invitation token |
| 170 | +- The backend validates the token and initiates a WebAuthn registration ceremony |
| 171 | +- After biometric authentication, the frontend calls `POST /embedded-wallets/passkey/registration/finish` with the credential |
| 172 | +- The backend queues a smart contract wallet deployment transaction with the public key |
| 173 | +- The Transaction Submission Service (TSS) deploys the contract to the Stellar network |
| 174 | +- Once deployed, the receiver's wallet is ready to receive funds |
| 175 | + |
| 176 | +:::tip Returning Users |
| 177 | + |
| 178 | +If a receiver already has a passkey for a different disbursement, they can simply authenticate with their existing passkey instead of creating a new one. The same passkey can be used across multiple disbursements. |
| 179 | + |
| 180 | +::: |
| 181 | + |
| 182 | +--- |
| 183 | + |
| 184 | +### Step 3: Complete Verification |
| 185 | + |
| 186 | +After creating their passkey, receivers are prompted to complete verification before they can receive funds: |
| 187 | + |
| 188 | + |
| 189 | + |
| 190 | +The verification step ensures that the receiver is who they claim to be. Depending on how you configured the disbursement, receivers may need to: |
| 191 | + |
| 192 | +- Enter an **OTP (One-Time Password)** sent to their email or phone |
| 193 | +- Provide their **date of birth** |
| 194 | +- Enter a **PIN** that was shared with them |
| 195 | +- Provide **national ID** information |
| 196 | + |
| 197 | +**What happens after verification:** |
| 198 | + |
| 199 | +1. The receiver submits their verification information |
| 200 | +2. The SDP validates the information against the receiver record |
| 201 | +3. If verification succeeds, the receiver wallet status changes from `READY` to `REGISTERED` |
| 202 | +4. The SDP automatically initiates the payment to the receiver's contract wallet address |
| 203 | + |
| 204 | +:::info Verification Flow |
| 205 | + |
| 206 | +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. |
| 207 | + |
| 208 | +For background on SEP-45 (contract-account web authentication), see [SEP-0045](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0045.md). |
| 209 | + |
| 210 | +::: |
| 211 | + |
| 212 | +--- |
| 213 | + |
| 214 | +### Step 4: Receiving Funds |
| 215 | + |
| 216 | +Once verification is complete, the SDP automatically transfers the disbursement amount to the receiver's smart contract wallet address. |
| 217 | + |
| 218 | +**Payment Process:** |
| 219 | + |
| 220 | +1. The SDP queues a payment transaction to the receiver's contract address |
| 221 | +2. The payment uses a **Stellar Asset Contract (SAC) transfer** to move funds from the distribution account to the contract wallet |
| 222 | +3. The transaction is **fee-sponsored** by the distribution account, so the receiver pays nothing |
| 223 | +4. Once confirmed on the network, the funds are available in the receiver's embedded wallet |
| 224 | + |
| 225 | +**What receivers see:** |
| 226 | + |
| 227 | +- The embedded wallet interface displays their asset balance |
| 228 | +- They can view their wallet address (a Stellar C-address starting with "C") |
| 229 | +- They can initiate transactions to send funds or withdraw to fiat |
| 230 | + |
| 231 | +## External Resources |
| 232 | + |
| 233 | +To learn more about the technologies behind Embedded Wallets, check out these resources: |
| 234 | + |
| 235 | +### Passkeys & WebAuthn |
| 236 | + |
| 237 | +- [passkeys.dev](https://passkeys.dev/) - Comprehensive guide to passkeys |
| 238 | +- [WebAuthn Specification](https://www.w3.org/TR/webauthn/) - W3C standard for web authentication |
| 239 | +- [FIDO Alliance](https://fidoalliance.org/) - The organization behind passkey standards |
| 240 | + |
| 241 | +### Stellar Protocols |
| 242 | + |
| 243 | +- [SEP-24: Hosted Deposit and Withdrawal](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md) - Interactive deposit/withdrawal flow |
| 244 | +- [SEP-45: Smart Contract Domain Verification](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0045.md) - Web authentication for smart contracts |
| 245 | +- [Stellar Asset Contract (SAC)](https://developers.stellar.org/docs/learn/smart-contract-internals/stellar-asset-contract) - Token standard for Stellar smart contracts |
| 246 | + |
| 247 | +### Smart Contracts |
| 248 | + |
| 249 | +- [Soroban Documentation](https://soroban.stellar.org/) - Stellar's smart contract platform |
| 250 | +- [Contract Address Format](https://developers.stellar.org/docs/learn/encyclopedia/contract-development/types/custom-types#addresses) - Understanding C-addresses vs G-addresses |
0 commit comments