068-tokens-roadmap.rst (8753B)
1 DD 68: Token Feature Roadmap 2 ############################ 3 4 :Design status: Draft 5 :Implementation status: Partial 6 :DD shepherd: TBD 7 :Historical contributors: Vlada Svirsh, Florian Dold 8 :First published: 2025-07-31 9 :Last substantive change: 2025-11-28 10 :Implementation evidence: taler-typescript-core (2025-09-22), sandcastle-ng (2025-09-25) 11 :Normative references: ``core/api-donau.rst``, ``core/api-merchant.rst``, ``wallet/wallet-core.md`` 12 13 .. note:: 14 15 This remains a roadmap. Existing Donau, merchant and wallet APIs are 16 normative for implemented functionality; subscription, discount and asset 17 milestones below do not imply implementation. 18 19 Summary 20 ======= 21 22 This design document documents the roadmap for token types 23 supported by Taler. 24 25 Motivation 26 ========== 27 28 Plan for Wallet 29 =============== 30 31 Types of tokens: 32 33 * donation tokens (original hard deadline: end of November 2025) 34 35 * onboarding (1st donation) 36 37 * ask for tax payer id, add taxOfficeBaseUrl (only one per wallet) 38 * can be changed, but new donations will have a different tax payer ID 39 * store date with tax payer ID for merge 40 41 * reporting: per year, one QR code per: (taxPayerId, walletSalt, year) 42 43 * meta data per QR code: taxPayerId, walletSalt, year, taxOfficeBaseUrl 44 * out of scope: generate PDF 45 * listing: just show sum (per tax payer ID and year and salt), not individual tokens 46 47 * listing: there is separate listing for tokens 48 * delete: out of scope for now / future work 49 50 * subscription 51 52 * listing 53 54 * Expired tokens are deleted automatically after grace period (30 days). 55 * Consider not deleting the last token of a particular slug. 56 Maybe in the future, subscription tokens will have a link 57 to re-purchase them. 58 * No counter 59 * Show expiration date 60 * delete (with big fat warning) 61 62 * discount tokens 63 64 * listing (type and number, description) 65 * group by expiration date (if it exists) 66 * delete 67 68 * asset tokens (original deadline: end of March 2026) 69 70 * listing (with number, no fractions possible, no expiration) 71 * background task: poll for share action, automatically execute the share action 72 73 * share action dividend: not supported for now 74 * share action voting: multiple in parallel possible, maybe show vote weight, have expiration date 75 * votes are grouped under the respective asset tokens 76 77 * voting action 78 79 * normally grouped under asset token ("history" for corporate actions) 80 * in notificiation state: vote directly or dismiss 81 * eventually, result is fetched and shown 82 83 * divident (initially out of scope) 84 85 * normally grouped under asset token ("history" for corporate actions) 86 * in notificiation state: dismiss, auto-dismiss after some time 87 88 89 Wallet UI Screenshots (Donau Integration) 90 ========================================= 91 92 Donau setup screen 93 ~~~~~~~~~~~~~~~~~~ 94 95 .. image:: ../screenshots/wallet/donau/donau-setup-android.png 96 :width: 50% 97 98 Balances view 99 ~~~~~~~~~~~~~ 100 101 .. image:: ../screenshots/wallet/donau/balances-android.png 102 :width: 50% 103 104 Donation statement 105 ~~~~~~~~~~~~~~~~~~ 106 107 .. image:: ../screenshots/wallet/donau/donation-statement-android.png 108 :width: 50% 109 110 Tax receipt available 111 ~~~~~~~~~~~~~~~~~~~~~ 112 113 .. image:: ../screenshots/wallet/donau/payment-android.png 114 :width: 50% 115 116 Tax receipt not available 117 ~~~~~~~~~~~~~~~~~~~~~~~~~ 118 119 .. image:: ../screenshots/wallet/donau/payment-notavailable-android.png 120 :width: 50% 121 122 Select Donau service 123 ~~~~~~~~~~~~~~~~~~~~ 124 125 .. image:: ../screenshots/wallet/donau/select-donau-android.png 126 :width: 50% 127 128 129 130 Plan for Merchant Backend 131 ========================= 132 133 Basic read-only contracts v1 support (release milestone 1.3, plan as of 2025-11-28): 134 135 * Rendering of orders (#10664): When the list of orders contains a v1 order 136 (for example created by the turnstile paywall), we should be able to render 137 it, instead of just saying "v1 unsupported". This is much less complex than 138 creating an order. We have the same fields as v0 plus choices (each choice 139 with its own inputs/outputs). It should be sufficient to use the existing 140 contract terms rendering and add the choices with inputs and outputs as a 141 list of sections. Since there is no specification yet for the contract terms 142 rendering, we just care about the raw information being accessible. 143 144 Creation of v1 contracts (release milestone 1.6, plan as of 2025-11-28): 145 146 * Creation of orders (#10665): There is 147 some preliminary design in the bug tracker, and once the time comes (1.6 148 milestone), we should do some sessions with her on the design. 149 * We might also think about ways that less technically experienced merchants 150 can use subscription/discount tokens, or could just leave this for integrations 151 like turnstile. 152 153 Improved and well-specified rendering of v1 contracts (release milestone >=1.6, plan as of 2025-11-28): 154 155 * We should have a DD describing the improved rendering of v1 contracts and 156 then implement this in the merchant and wallet. 157 * The merchant backend might also need to learn to show the preliminary contract terms 158 of orders that have not been claimed yet (#10615). 159 160 161 Plan for Donau 162 ============== 163 164 * Service exists 165 * Needs to packaged 166 167 168 User Experience 169 =============== 170 171 Donau MVP 172 ~~~~~~~~~ 173 174 **Donor / wallet user:** 175 176 1. User opens Taler wallet, goes to ``Settings -> Donations`` 177 2. In the initial state, user can enter a donau base URL and tax ID. 178 3. Subsequently, the ``Settings -> Donations`` screen shows: 179 180 * Currently configured donation authority 181 * Currently configured tax ID 182 * Navigation link ``Show donation statements`` 183 184 4. User makes a payment with a merchant that offers donation receipts. 185 If the merchant supports the same donau service as configured in the wallet, 186 the wallet UI shows some notice (e.g. ``This payment provides a donation receipt``). 187 188 5. User can view their current donation statement via ``Overview -> Donation statements``. 189 190 **Merchant:** 191 192 In the MVP, the merchant backend will be set up via the REST API, 193 we won't provide any SPA support. 194 195 Donau Next Iteration 196 ~~~~~~~~~~~~~~~~~~~~ 197 198 **Donor / wallet user:** 199 200 In the post-MVP iteration, we want to improve the onboarding experience. The 201 wallet should ask *during* a payment that supports a donation receipt if the 202 user wants to set up donation receipts. 203 204 As the merchant might offer multiple donau URLs (each for their own financial domain), 205 the user needs to be shown all possible donaus with their respective financial domain. 206 After choosing the donau, the user needs to enter their tax payer identifier. 207 208 **Merchant:** 209 210 In the post-MVP iteration, the merchant SPA should allow a merchant 211 to set up the donau integration. This includes the following steps: 212 213 1. The merchant registers a charity ID with the donau. 214 215 * The SPA should probably explain this process and 216 show the merchant public key, which needs to be given 217 to the donation authority for the charity registration process. 218 * The actual registration happens via a side channel (e-mail, postal, in 219 person, ...), there is no protocol for this. 220 * As a result of the registration, the merchant obtains a ``charity_id`` 221 222 2. The merchant SPA provides a configuration page for the 223 supported donation authorities, where the merchant can enter the donau base URL 224 and charity ID. 225 226 3. For each configured charity, there should be a details page 227 that shows the used and remaining donation amount. 228 229 4. When creating an order via the SPA, there should be an option 230 labled "this is a donation". 231 232 233 234 Test Plan 235 ========= 236 237 * Subscription/discount: blog.demo.taler.net 238 * Donations: donations.demo.taler.net 239 240 * Receipt validation: TBD 241 242 * Asset tokenization: TBD / will be deployed on demo via merchant 243 244 245 Donations: donations.demo.taler.net 246 =================================== 247 248 Donate page 249 ~~~~~~~~~~~~ 250 251 .. image:: ../screenshots/donau/donate-web.png 252 253 Payment method selection 254 ~~~~~~~~~~~~~~~~~~~~~~~~ 255 256 .. image:: ../screenshots/donau/payment-method-web.png 257 258 Taler Pay 259 ~~~~~~~~~ 260 261 .. image:: ../screenshots/donau/taler-pay.png 262 263 Receipt page 264 ~~~~~~~~~~~~ 265 266 .. image:: ../screenshots/donau/receipt-web.png 267 268 269 Donau Verify UI 270 =============== 271 272 Donau verification (input) 273 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 274 275 .. image:: ../screenshots/donau/donau-verify.png 276 :width: 50% 277 278 Donau verification (verified) 279 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 280 281 .. image:: ../screenshots/donau/donau-verified.png 282 :width: 50% 283 284 285 Definition of Done 286 ================== 287 288 * [x] Donau deployed in sandcastle 289 * [x] demo donation setup uses Donau and contract terms v1 290 * [ ] separate receipt-verification app completed and deployment verified 291 292 Discussion / Q&A 293 ================ 294 295 (This should be filled in with results from discussions on mailing lists / personal communication.)