taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

100-shares.rst (19382B)


      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-11-14
     10 
     11 Summary
     12 =======
     13 
     14 This document specifies how GNU Taler can be used to support *registered*
     15 shares (*Namensaktien*) for which a new *share register* keeps the
     16 authoritative record of the registered shareholders and of the number of
     17 shares attributed to each of them.  The new *share register* provides the
     18 cryptographic machinery for recording issuance, transfer, dividends and
     19 e-voting based on shares held.  The share register is maintained by the issuer
     20 or by an operator designated by the issuer and modifying it is guarded by
     21 requiring consent from an independent second party, the *share guard*.  The
     22 Taler exchange and merchant continue to process the electronic-money payments
     23 used to buy or sell shares and to receive dividends.
     24 
     25 Private *shareholder keys* stored in the Taler wallets only serve to authorize
     26 certain operations on the shares (such as withdrawing dividends, e-voting or
     27 receiving information from the company). They also can serve as one of
     28 *multiple authentication factors* required to authorize selling shares.  Any
     29 change of the registered ownership of a share is only effective once it has
     30 been processed by the share register and authorized by the share guard.  A
     31 transfer request starts the process to update the register, and only a
     32 successful registration in the register and approval by the share guard
     33 triggers the issuance of share tokens to the buyer.
     34 
     35 Motivation
     36 ==========
     37 
     38 Taler can tokenize assets other than fiat-money or crypto-currencies.
     39 One asset class that could be particularly promising are shares in
     40 companies. This design document specifies how Taler could be used to
     41 tokenize shares and pay out dividends.
     42 
     43 For registered shares, the system must associate every share position with an
     44 identified shareholder and keep a reliable record of the changes of ownership.
     45 Simply moving bearer-style tokens from one wallet to another would not keep
     46 the wallet balances and the shareholder register synchronized and not meet
     47 legal registration requirement.  Furthermore, the law requires an independent
     48 entity to approve every update to the register.  The design therefore does not
     49 directly use the Taler cryptography to represent shares, but merely integrates
     50 with it for buying and selling shares against cash, issuing new shares against
     51 cash, paying out dividends and providing e-voting tokens for shareholder
     52 decisions. Storing private shareholder keys in the Taler wallet is also convenient
     53 as a way to provide an additional authentication factor that is backed up with
     54 the regular wallet backup mechanisms.  The actual implementation is provided
     55 by new shareholder register and register guard components.
     56 
     57 Requirements
     58 ============
     59 
     60 User stories include:
     61 
     62 - emit shares for fiat money (raising capital), showing investor brief / shareholder agreement before purchase
     63 - sell of shares by a shareholder for fiat money to a new shareholders
     64 - sell of shares by a shareholder for fiat money to existing shareholders
     65 - buy shares for fiat money from existing shareholders as a new shareholder (with legitimization)
     66 - buy shares for fiat money from existing shareholders as an existing shareholder (without legitimization)
     67 - issue dividends from the business to shareholders
     68 - notify shareholders about business developments, such as shareholder meetings
     69 - issue shareholders e-voting tokens using blind signatures to enable voting on business decisions
     70 
     71 Enabling shareholders to vote (e-voting) on business decisions is out of
     72 scope for this initial design and left for a future design document.
     73 
     74 The share register must in particular:
     75 
     76 - register shareholders following a successful legitimization (identity verification) step
     77   and confirmation from the register guard
     78 - record the allocation of newly issued shares to identified shareholders after
     79   approval by the register guard
     80 - initiate a transfer by reserving shares and complete the transfer to a
     81   registered shareholder upon confirmation from the register guard;
     82   the reservation must prevent the same shares from being used in
     83   multiple concurrent transfers, and it must expire if the transfer does
     84   not complete by some deadline; proof of payment by the buyer before
     85   the deadline must be the last step
     86 - record which shareholders have outstanding dividends for a particular
     87   period, and updating the outstanding dividend amount atomically
     88   when irrevokably paying the dividend
     89 - record which shareholders have received ballots for a particular
     90   vote
     91 - maintain an auditable history of share issuances, transfers, redemptions and
     92   dividend distributions
     93 
     94 Electronic-money payments continue to use the existing Taler exchange:
     95 share-specific functionality must not be implemented as a new asset class
     96 inside the exchange itself (see `Alternatives`_).
     97 
     98 
     99 Proposed Solution
    100 =================
    101 
    102 Components
    103 ----------
    104 
    105 A share register service is introduced to a avoid overloading existing
    106 components with share-specific responsibilities.  The components have the
    107 following responsibilities:
    108 
    109 - **share register**: the REST API and backend for share purchases, transfers and
    110   shareholder information, including the relevant legal documents
    111 - **share guard**: independent 2nd party receiving additional authorizations (MFA)
    112   for share transfers; its consent is required for critical updates to the
    113   share register (Note: find out what is legally critical and what is not!)
    114 - **merchant backend**: purchase orders, payment references and the integration
    115   with Taler's contracts
    116 - **exchange**: the electronic-money operations, that is the purchase payments
    117   and the dividend payouts
    118 
    119   
    120 Share Tokens
    121 ------------
    122 
    123 Shares are something the new share register allows users to buy and sell
    124 (or the company to emit):
    125 
    126 - shareholder registration records legitimization data (at least
    127   3 factors) with both share register and share guard. Only registered
    128   shareholders are allowed to transact with shares. One of the
    129   factors is a private shareholder key stored in each wallet.
    130   For some operations the private shareholder key may be configured
    131   to suffice to authorize them. Some factors are exclusively used
    132   by the share guard.
    133 - share register tracks number of shares issued to each registered
    134   shareholder
    135 - buying shares is a regular contract with the contract terms
    136   specifying the number of shares to be transferred; it must
    137   additionally be signed by the private shareholder keys of buyer
    138   and seller.
    139   The contract only
    140   becomes valid with the signatures of share register and share guard;
    141   the share guard requires at least one more authentication factor
    142   by the seller before providing its signature.
    143   Share register and share guard update the register upon receiving
    144   confirmation of the payment by the exchange during the reservation
    145   window. The wallet of the buyer understands the share purchase
    146   contract and only signs the deposit confirmations if all required
    147   approvals are present and the time is significantly before the
    148   end of the reservation window.
    149 - the share register includes endpoints to send notifications to wallets
    150   for issued shares, such as dividend notifications or shareholder
    151   meeting announcements; wallets should request updates at a
    152   frequency specified in /config of the share register; all notifications are
    153   ordered (numerically), with an endpoint to list all notifications
    154   past a given serial ID, and another to download each of the
    155   (historic) notifications; once issued, notifications never change;
    156   notifications are signed by a long-term share register key.
    157 - wallets can use their private shareholder key to request dividend distribution.
    158   Dividend distribution happens via a new type of contract where
    159   either a p2p-pull request instructs to pay to a wallet, or where
    160   a deposit request instructs the share register to deposit the funds
    161   into a bank account.
    162   Note that the share register should handle the case where it
    163   does not directly make the payment and merely exports
    164   the list of dividend payment requests (with signatures) to its operator.
    165   It might be good if it could see if the operator satisfied the
    166   request.
    167 - the share-register allows admin to emit new shares; as always,
    168   the share-guard must confirm.
    169 - all requests are stored, and a single sequential timeline is
    170   preserved by linking them blockchain-style, ensuring a single
    171   top-level hash is enough to check consistency between
    172   share-register and share-guard.
    173 
    174 
    175 Shareholder Register
    176 --------------------
    177 
    178 A new share register service maintains the shareholder records and the share
    179 positions.  Every shareholder has a unique internal identifier that is
    180 associated with a verified customer identity.  The service stores the
    181 information required for the register and keeps a history of all changes.
    182 
    183 The register contains at least:
    184 
    185 - the shareholder identifier and the required shareholder information
    186 - the relevant share class
    187 - the number of shares attributed to each shareholder
    188 - the registration date and the applicable effective date of each change
    189 - references to the transactions that caused each change
    190 
    191 The register is authoritative for determining which shareholder is recorded as
    192 holding a given number of shares.
    193 
    194 Every register change is recorded as an immutable event.  Events include:
    195 
    196 - the initial share issuance
    197 - the allocation of newly issued shares
    198 - a transfer between shareholders
    199 - a share buyback or cancellation
    200 - a correction of a previously recorded event
    201 - any other change affecting a shareholder's position
    202 
    203 The register must support reconstructing the shareholder positions at an
    204 earlier point in time.  The current position may be stored as a materialized
    205 balance, but every change must be traceable to a recorded register event.
    206 
    207 An event records the affected shareholders, the share class, the quantity, the
    208 effective time, the recording time and the corresponding transaction
    209 identifier.  Corrections are represented by additional events rather than by
    210 silently overwriting historical records.  The service maintains the current
    211 share positions derived from these events and provides the audit trail used for
    212 reconciliation.
    213 
    214 
    215 Shareholder MFA update
    216 ----------------------
    217 
    218 Using a sufficient number of authorization mechanisms (possibly excluding the
    219 private shareholder key) the share register and share guard allow the
    220 shareholder to update the authorization mechanisms and to update their
    221 legitimization data. This could in particular involve online legitimization
    222 against the existing legitimization records.
    223 
    224 Todo: which authorization mechanisms should be implemented, what are good
    225 thresholds for sufficient, are they configurable, and if so by the share
    226 register/guard or by the shareholder individually?
    227 
    228 
    229 Share Issuance
    230 --------------
    231 
    232 Shares are purchased through the share register, which uses a merchant
    233 backend for the purchase order and for the payment.  The buyer must have a
    234 verified shareholder identity before a purchase can be completed.
    235 
    236 For example, a customer purchases ten shares at EUR 100 each:
    237 
    238 0. the share register and share guard register the buyer,
    239    with its shareholder public key and additional authorization
    240    factors
    241 1. share register and share guard confirm the sell authorization of
    242    the issuer and reserve the shares from the issuer's quota
    243 2. the share register creates a purchase order for ten shares,
    244    including the public shareholder key of the buyer at a merchant backend
    245 3. the customer pays EUR 1000 using their Taler wallet
    246 4. the merchant backend confirms the successful payment
    247 5. the share register and share guard verify the payment
    248    and update the register, both arrive at the same hash
    249    chain and sign the update; with both signatures, the update
    250    is complete
    251 6. only following the successful registration does the private
    252    shareholder key of the buyer yield rights to the shares
    253 
    254 Note: do we need some logic to refund share
    255 purchase prices if the share issuance date expired without the
    256 transfer having been executed?
    257 
    258 
    259 Share Transfer
    260 --------------
    261 
    262 A transfer begins when a shareholder initiates a transfer of share tokens to
    263 another party.  Such a transfer is treated as a *request* to sell or transfer
    264 the corresponding share position, and not as an unconditional transfer of the
    265 registered shares.
    266 
    267 The transfer protocol proceeds as follows:
    268 
    269 1. the recipient is identified and verified against the applicable eligibility
    270    requirements; the recipient's wallet must be bound to a verified customer
    271    identity (see `Identity and Privacy`_)
    272 2. the seller initiates a transfer of a given number of shares
    273 3. the share register service checks the seller's registered position, the
    274    requested quantity and any applicable transfer restrictions
    275 4. the share backend creates a unique transfer request and *reserves* the
    276    corresponding tokens, or otherwise prevents their concurrent use
    277 5. the share guard also receives and authorization for the sale and adds
    278    its own signature
    279 6. an pay-pull request is created by the wallet of the seller with all of
    280    the authorizations, including the public shareholder key of the buyer
    281 7. the successful payment event (proof of purchase) transfers
    282    the rights to the corresponding shares to the buyer; the buyer has
    283    time to submit their proof of purchase until the reservation expires
    284    to either the share register or the share guard
    285 8. both the share register and the share
    286    guard sign over the new share register chain head including a date and all of the
    287    share transfers since the last generation. Once both signatures are present,
    288    the register is considered *consistent*.  Reservations only expire after
    289    a new share register generation has achieved consistency and where the
    290    respective reservation is either marked
    291    as expired (date above expiration) or where the share transfer was executed.
    292 
    293 
    294 Dividends and Ballot Token Generation
    295 -------------------------------------
    296 
    297 For registered shares, the share backend determines the number of shares
    298 eligible for the distribution and the corresponding dividend amount from the
    299 shareholder register and the applicable entitlement rules.
    300 
    301 For example, a shareholder holds ten shares and is entitled to a dividend of
    302 EUR 1 per share.  The share register would then *increase* their dividend
    303 entitlement by EUR 10, adding the new entitlement on top of one that might
    304 be outstanding from a previous round.
    305 
    306 The share position itself remains unchanged.  The backend must ensure that
    307 each dividend entitlement can be claimed only once.  It must also handle
    308 transfer requests consistently around the applicable dividend entitlement date
    309 so that it is clear if shares are reserved for transfer before or after a
    310 dividend distribution.
    311 
    312 
    313 
    314 Data Model
    315 ----------
    316 
    317 The implementation requires persistent records for:
    318 
    319 - shareholders and their verified customer identities
    320 - share classes and issued shares
    321 - the current shareholder positions
    322 - purchase orders and the associated payments
    323 - share transfer requests and their states
    324 - share register events
    325 - share token generations and issuance records
    326 - dividend distributions and individual entitlement claims
    327 - token refresh operations and electronic-money payouts
    328 
    329 Every operation must have a unique identifier that connects the relevant
    330 payment, register event and token operation.
    331 
    332 
    333 Identity and Privacy
    334 --------------------
    335 
    336 The share register uses the customer identity established through the
    337 applicable verification process.  Private shareholder keys in wallets are
    338 associated with customer identities through explicit backend records; a wallet
    339 identifier alone must not be treated as proof of a shareholder's authoriztion.
    340 
    341 Identity information should only be exposed to the components that require it.
    342 The protocols should use transaction references and other strictly
    343 necessary technical identifiers instead of unnecessarily distributing personal
    344 information.
    345 
    346 
    347 Audit and Reconciliation
    348 ------------------------
    349 
    350 The system must support reconciliation between:
    351 
    352 - the share register and the share guard
    353 - the merchant/exchange payments for shares
    354 - the dividend entitlements and payouts
    355 
    356 The reconciliation process must identify discrepancies such as
    357 incomplete transfers, duplicate processing attempts and unpaid
    358 dividend obligations.
    359 
    360 A transfer or dividend operation must not be considered complete merely because
    361 a request was submitted: completion requires the relevant register and token
    362 operations to have reached their defined successful states.
    363 
    364 Test Plan
    365 =========
    366 
    367 - backend logic to issue, sell, buy shares
    368 - pay out dividends
    369 - wallet-core and wallet-UI tests
    370 - initial issuance of shares following a successful payment and registration
    371 - rejection of purchases by customers that do not satisfy the eligibility
    372   requirements
    373 - transfers between registered shareholders
    374 - rejection of transfers to ineligible recipients
    375 - concurrent transfer requests involving the same tokens
    376 - failed registration with safe cancellation or retry
    377 - repeated processing of the same registration event without duplicate issuance
    378 - refresh from one share-token generation to the next
    379 - correct dividend calculation and payout
    380 - reconciliation between register positions and token issuance records
    381 - recovery following a service interruption between registration and token
    382   issuance
    383 
    384 Definition of Done
    385 ==================
    386 
    387 - shares can be purchased using ordinary Taler digital cash
    388 - a successful purchase results in a registered shareholder position and in the
    389   corresponding share tokens
    390 - transfers initiate a registration process and do not issue tokens to the
    391   recipient before the registration succeeded
    392 - failed transfers do not create shares
    393 - all operations can be audited and reconciled
    394 - the wallet and the merchant backend can recover safely from retries and
    395   interruptions
    396 
    397 Alternatives
    398 ============
    399 
    400 - Using the exchange as the emitter of shares; not so good as it is
    401   single-currency by design and not setup for dealing with purchases;
    402   it might make p2p transfers easier, but regulation on trading is
    403   different for shares and the mismatch is likely big enough that
    404   not overloading the exchange code with is it is a good idea.
    405 - Using the merchant backend as the emitter of shares; again, there
    406   is a mismatch in requirements and combining the two is likely to
    407   increase technical complexity without adequate gains.
    408 - Transferring bearer-style share tokens between wallets without a
    409   registration step; this does not provide the synchronization between wallet
    410   balances and the shareholder register that registered shares require.
    411 
    412 Drawbacks
    413 =========
    414 
    415 
    416 
    417 Open Questions
    418 ==============
    419 
    420 The implementation must be reviewed against the applicable corporate-law and
    421 securities-law requirements before deployment.  The design separates the
    422 technical representation of the shares from the shareholder register, but that
    423 separation alone does not establish the legal classification of the tokens or
    424 the regulatory status of the resulting system.
    425 
    426 Discussion / Q&A
    427 ================
    428 
    429 (This should be filled in with results from discussions on mailing lists / personal communication.)