100-shares.rst (6020B)
1 DD 100: Share Tokenization 2 ########################## 3 4 :Design status: Draft 5 :Implementation status: Not started 6 :DD shepherd: TBD 7 :Historical contributors: Christian Grothoff 8 :First published: 2026-08-09 9 :Last substantive change: 2026-08-18 10 11 Summary 12 ======= 13 14 15 Motivation 16 ========== 17 18 Taler can tokenize assets other than fiat-money or crypto-currencies. 19 One asset class that could be particularly promising are shares in 20 companies. This design document specifies how Taler could be used to 21 tokenize shares and pay out dividends. 22 23 Requirements 24 ============ 25 26 - emit shares for fiat money (raising capital), showing investor brief / shareholder agreement before purchase 27 - sell shares for fiat money to new shareholders 28 - buy shares for fiat money from existing shareholders 29 - issue dividends from the business to shareholders 30 - notify shareholders about business developments, such as shareholder meetings 31 32 Enabling shareholders to vote (e-voiting) on business decisions is out of 33 scope for this initial design and left for a future design document. 34 35 36 Proposed Solution 37 ================= 38 39 Shares are something a new frontend allows users to buy and sell 40 (or the company to emit) using a traditional merchant backend for 41 the cryptographic part: 42 43 - add new token family "shares" in the merchant backend; it includes 44 new meta-data for wallets to learn about notifications and dividends 45 from the (new) frontend 46 - share token families have a generation, like 2024 and 2025, where 47 the contract for selling 2024 tokens for 2025 tokens yields 48 the dividend (see below) 49 - merchant backend tracks number of shares issued and bought back, 50 thus knows number of shares outstanding 51 - buying shares is a regular v1 contract with share tokens as outputs 52 and Taler payments in digital cash are inputs; the token family 53 references the shareholder agreement (must not be forgotten with the 54 purchase details) 55 - new frontend includes endpoints to send notifications to wallets 56 for issued shares, such as dividend notifications or shareholder 57 meeting announcements; wallets should request updates at a 58 frequency specified with the token family; all notifications are 59 ordered (numerically), with an endpoint to list all notifications 60 past a given serial ID, and another to download each of the 61 (historic) notifications; once issued, notifications never change; 62 notifications are signed by a long-term frontend key; note that 63 we probably want these announcements to be managed by the merchant 64 backend as a new feature: this way, all of the auditing can focus 65 just on the merchant backend 66 67 Notification endpoint ownership is therefore an open design decision: the 68 initial frontend-owned proposal and the merchant-backend alternative above 69 must be resolved before the API is specified. 70 71 - new frontend includes its own wallet; it is used to pay dividends; 72 wallets can request a contract to sell generation X shares for 73 generation X+1 shares (once a notification has been posted that 74 dividends for generation X shares are available). In that contract, 75 the wallet_data includes either a p2p-pull request that tells the 76 frontend where to pay the dividend (from its local wallet); 77 note that the frontend probably should handle the case where the 78 local wallet does not have the required balance and merely exports 79 the list of p2p-pull requests instead of executing them immediately 80 - new frontend tracks order-book with buy and sell orders, allowing 81 share owners to indicate the number of shares they want to buy or 82 sell at a certain price; these bids must be *backed* by tokens 83 (money or shares) with signatures to buy or sell the respective 84 amount of stock at the given price; double-spending is NOT yet 85 detected when the order is made, but deferred up to the moment 86 where the order would be executed; here the frontend would use 87 a transient wallet: the buy order would be for an already 88 signed contract to buy shares, the sell order would include a 89 p2p-pull request to be satisfied; by giving the buyer the new 90 shares the frontend would be paid (into its bank account) and 91 could then (possibly delayed) use those funds to satisfy the 92 p2p-pull request from the seller; as above, a frontend-integrated 93 wallet may be able to immediately pay the p2p-pull requests (if 94 its balance is sufficient), or the p2p-pull requests are exported 95 to the administrator to be executed later 96 - new frontend allows admin to emit new shares (picks best bids from 97 order-book at the deadline, possibly conditional upon top N-bids 98 exceeding minimum investment, or top N-bids being above minimum 99 price) 100 - all requests are stored, and there is a new merchant auditor that 101 inspects the share transaction data and checks if all p2p-pull requests 102 have been paid out (the existing merchant backend reconciliation 103 logic should naturally already check the incoming deposits). 104 Note that the order book itself probably does NOT need to be in 105 the merchant backend, but we could keep it there as well (to keep 106 the new frontend "stateless"; in that case, we'd also want to track 107 the p2p-pull requests in the merchant backend) 108 109 Test Plan 110 ========= 111 112 - backend logic to issue, sell, buy shares 113 - pay out dividends 114 - wallet-core and wallet-UI tests 115 116 117 Definition of Done 118 ================== 119 120 (Only applicable to design documents that describe a new feature. While the 121 DoD is not satisfied yet, a user-facing feature **must** be behind a feature 122 flag or dev-mode flag.) 123 124 Alternatives 125 ============ 126 127 - Using the exchange as the emitter of shares; not so good as it is 128 single-currency by design and not setup for dealing with purchases; 129 it might make p2p transfers easier, but regulation on trading is 130 different for shares and the mismatch is likely big enough that 131 not overloading the exchange code with is it is a good idea. 132 133 134 135 Drawbacks 136 ========= 137 138 139 140 Discussion / Q&A 141 ================ 142 143 (This should be filled in with results from discussions on mailing lists / personal communication.)