commit 42227202ed7a660187ca3990a75bf54cf4f94503
parent 158c72b4ee0c705fbcebd8f59cd5c504f68b379b
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 24 Oct 2026 19:47:47 +0200
Merging requirements analysis from Damian.
Diffstat:
1 file changed, 303 insertions(+), 7 deletions(-)
diff --git a/design-documents/100-shares.rst b/design-documents/100-shares.rst
@@ -6,11 +6,26 @@ DD 100: Share Tokenization
:DD shepherd: TBD
:Historical contributors: Christian Grothoff
:First published: 2026-08-09
-:Last substantive change: 2026-08-18
+:Last substantive change: 2026-10-24
Summary
=======
+This document specifies how GNU Taler can tokenize shares in companies, how
+such shares can be traded and how dividends are paid out. Share positions are
+represented by share tokens held in the users' wallets, the merchant backend
+provides the cryptographic machinery for the issuance, transfer and renewal of
+those tokens, and the Taler exchange continues to process the
+electronic-money payments used to buy shares and to receive dividends.
+
+For *registered* shares (*Namensaktien*) the design adds a share register that
+keeps the authoritative record of the registered shareholders and of the number
+of shares attributed to each of them. The register is maintained by the issuer
+or by an operator designated by the issuer. Here the central principle is that
+share tokens only represent share positions *technically*: a change of the
+registered ownership of a share is processed by the share register. A transfer
+request starts the registration process, and only a successful registration
+triggers the issuance of share tokens to the buyer.
Motivation
==========
@@ -20,6 +35,15 @@ One asset class that could be particularly promising are shares in
companies. This design document specifies how Taler could be used to
tokenize shares and pay out dividends.
+For registered shares, the system must additionally associate every share
+position with an identified shareholder and keep a reliable record of the
+changes of ownership. Simply moving bearer-style tokens from one wallet to
+another would not by itself keep the wallet balances and the shareholder
+register synchronized. The design therefore introduces an explicit
+registration step into the share transfer protocol: this retains the
+cryptographic and payment-processing mechanisms of GNU Taler while maintaining
+a separate, auditable shareholder register.
+
Requirements
============
@@ -32,10 +56,36 @@ Requirements
Enabling shareholders to vote (e-voiting) on business decisions is out of
scope for this initial design and left for a future design document.
+For registered shares, the system must additionally be able to:
+
+- register shareholders following a successful identity verification
+- record the allocation of newly issued shares to identified shareholders
+- represent the registered share positions using share tokens
+- initiate a transfer by presenting or transferring share tokens through the
+ share-transfer protocol
+- verify the identity and the eligibility of the recipient before a transfer is
+ completed
+- update the shareholder register before replacement share tokens are issued to
+ the recipient
+- prevent the same share tokens from being used in multiple concurrent
+ transfers
+- exchange share tokens of one generation for tokens of the next generation
+ while paying the corresponding dividend
+- maintain an auditable history of share issuances, transfers, redemptions and
+ dividend distributions
+- reconcile the shareholder register, the issued share tokens and the completed
+ transactions
+
+Electronic-money payments continue to use the existing Taler exchange:
+share-specific functionality must not be implemented as a new asset class
+inside the exchange itself (see `Alternatives`_).
Proposed Solution
=================
+Share Tokens, Frontend and Order Book
+-------------------------------------
+
Shares are something a new frontend allows users to buy and sell
(or the company to emit) using a traditional merchant backend for
the cryptographic part:
@@ -106,20 +156,256 @@ must be resolved before the API is specified.
the new frontend "stateless"; in that case, we'd also want to track
the p2p-pull requests in the merchant backend)
+Registered Shares
+-----------------
+
+For registered shares, the design separates three functions:
+
+- the share register maintains the authoritative record of the registered
+ shareholders and of their share positions
+- the merchant backend and the share-token functionality handle the issuance,
+ the transfer requests and the renewal of share tokens
+- the Taler exchange processes the electronic-money payments used to purchase
+ shares and to receive dividends
+
+Shareholder Register
+--------------------
+
+A new share register service maintains the shareholder records and the share
+positions. Every shareholder has a unique internal identifier that is
+associated with a verified customer identity. The service stores the
+information required for the register and keeps a history of all changes.
+
+The register contains at least:
+
+- the shareholder identifier and the required shareholder information
+- the relevant share class
+- the number of shares attributed to each shareholder
+- the registration date and the applicable effective date of each change
+- references to the transactions that caused each change
+
+The register must support reconstructing the shareholder positions at an
+earlier point in time. The current position may be stored as a materialized
+balance, but every change must be traceable to a recorded register event.
+
+The register is authoritative for determining which shareholder is recorded as
+holding a given number of shares. Wallet balances must not be used as a
+substitute for the register.
+
+Share Issuance
+--------------
+
+Shares are purchased through the new web frontend, which uses the merchant
+backend for the purchase order and for the payment. The buyer must have a
+verified customer identity before a purchase can be completed.
+
+For example, a customer purchases ten shares at EUR 100 each:
+
+1. the frontend creates a purchase order for ten shares
+2. the customer pays EUR 1000 using their Taler wallet
+3. the merchant backend confirms the successful payment
+4. the share register service verifies the purchase order, the customer
+ identity, the payment reference and the availability of shares
+5. the service records the allocation of ten shares to the shareholder
+6. only following the successful registration does the share-token
+ functionality issue ten share tokens into the buyer's wallet
+
+Share Transfer
+--------------
+
+A transfer begins when a shareholder initiates a transfer of share tokens to
+another party. Such a transfer is treated as a *request* to sell or transfer
+the corresponding share position, and not as an unconditional transfer of the
+registered shares.
+
+The transfer protocol proceeds as follows:
+
+1. the seller initiates a transfer of a given number of share tokens (sending
+ share tokens to another wallet, possibly as a share/money swap)
+2. the share backend creates a unique transfer request and reserves the
+ corresponding tokens, or otherwise prevents their concurrent use
+3. the recipient is identified and verified against the applicable eligibility
+ requirements; the recipient's wallet must be bound to a verified customer
+ identity (see `Identity and Privacy`_)
+4. the share register service checks the seller's registered position, the
+ requested quantity and any applicable transfer restrictions
+5. if all required conditions are satisfied, the register records the change of
+ the shareholder attribution
+6. the successful register event triggers the issuance of the corresponding
+ share tokens to the buyer
+7. the transfer is marked as completed once the token issuance has been
+ confirmed
+
+For example, a shareholder holding ten shares transfers five shares to another
+registered shareholder. Before the transfer, the register records ten shares
+for the seller and none for the buyer; after the successful registration, it
+records five shares for each of them. The seller retains five share tokens and
+the buyer receives five newly issued share tokens.
+
+The buyer's tokens must not be issued before the register change has succeeded.
+If the registration fails, the system must not issue tokens to the buyer; the
+transfer request must then either be safely retried or cancelled, with any
+reservation released according to the transfer protocol. The transfer process
+must prevent double-spending and must ensure that two concurrent requests
+cannot transfer the same registered share position twice.
+
+Share Register Events
+---------------------
+
+Every register change is recorded as an immutable event. Events include:
+
+- the initial share issuance
+- the allocation of newly issued shares
+- a transfer between shareholders
+- a share buyback or cancellation
+- a correction of a previously recorded event
+- any other change affecting a shareholder's position
+
+An event records the affected shareholders, the share class, the quantity, the
+effective time, the recording time and the corresponding transaction
+identifier. Corrections are represented by additional events rather than by
+silently overwriting historical records. The service maintains the current
+share positions derived from these events and provides the audit trail used for
+reconciliation.
+
+Dividends and Share Token Generations
+-------------------------------------
+
+As described above, share tokens have a generation, such as 2026 or 2027, which
+identifies the token series used for a particular dividend distribution period.
+When a dividend becomes available, a notification identifying the relevant
+generation and distribution is published, and a wallet holding tokens of
+generation X may then request a contract to exchange those tokens for
+generation X+1 tokens.
+
+For registered shares, the share backend determines the number of shares
+eligible for the distribution and the corresponding dividend amount from the
+shareholder register and the applicable entitlement rules, and not merely from
+the number of tokens presented by the wallet.
+
+For example, a shareholder holds ten shares and is entitled to a dividend of
+EUR 1 per share. The refresh then results in:
+
+- ten tokens of generation X being redeemed
+- ten tokens of generation X+1 being issued
+- EUR 10 being paid into the shareholder's wallet as ordinary Taler digital
+ cash
+
+The share position itself remains unchanged: only the token generation changes,
+and the dividend is paid separately. The backend must ensure that each
+dividend entitlement can be claimed only once. It must also handle transfers
+and refresh requests consistently around the applicable dividend entitlement
+date.
+
+Separation of Components
+------------------------
+
+The share register service is introduced precisely so that the exchange is not
+overloaded with share-specific responsibilities. The components have the
+following responsibilities:
+
+- **web frontend**: the user interface for share purchases, transfers and
+ shareholder information, including the relevant legal documents
+- **merchant backend**: purchase orders, payment references and the integration
+ with Taler's contract and token mechanisms
+- **share register service**: the shareholder records, the validation of
+ register changes, and the decision when a token issuance may proceed
+- **share-token functionality**: issuance, redemption and refresh of share
+ tokens, and the coordination of the associated transfer and dividend
+ operations
+- **exchange**: the electronic-money operations, that is the purchase payments
+ and the dividend payouts
+
+The share register service and the share-token functionality may initially be
+implemented as components of the same application, provided that their
+responsibilities and their data integrity requirements remain clearly
+separated.
+
+Data Model
+----------
+
+The implementation requires persistent records for:
+
+- shareholders and their verified customer identities
+- share classes and issued shares
+- the current shareholder positions
+- purchase orders and the associated payments
+- share transfer requests and their states
+- share register events
+- share token generations and issuance records
+- dividend distributions and individual entitlement claims
+- token refresh operations and electronic-money payouts
+
+Every operation must have a unique identifier that connects the relevant
+payment, register event and token operation.
+
+Identity and Privacy
+--------------------
+
+The share register uses the customer identity established through the
+applicable verification process. Wallet identifiers are associated with
+customer identities through explicit backend records; a wallet identifier alone
+must not be treated as proof of a shareholder's identity.
+
+Identity information should only be exposed to the components that require it.
+The token protocols should use transaction references and other strictly
+necessary technical identifiers instead of unnecessarily distributing personal
+information.
+
+Audit and Reconciliation
+------------------------
+
+In addition to the merchant auditor described above, the system must support
+reconciliation between:
+
+- the shareholder register
+- the issued and redeemed share tokens
+- the pending and completed transfer requests
+- the purchase payments
+- the dividend entitlements and payouts
+
+The reconciliation process must identify discrepancies such as missing token
+issuances, incomplete transfers, duplicate processing attempts and unpaid
+dividend obligations.
+
+A transfer or dividend operation must not be considered complete merely because
+a request was submitted: completion requires the relevant register and token
+operations to have reached their defined successful states.
+
Test Plan
=========
- backend logic to issue, sell, buy shares
- pay out dividends
- wallet-core and wallet-UI tests
-
+- initial issuance of shares following a successful payment and registration
+- rejection of purchases by customers that do not satisfy the eligibility
+ requirements
+- transfers between registered shareholders
+- rejection of transfers to ineligible recipients
+- concurrent transfer requests involving the same tokens
+- failed registration with safe cancellation or retry
+- repeated processing of the same registration event without duplicate issuance
+- refresh from one share-token generation to the next
+- correct dividend calculation and payout
+- reconciliation between register positions and token issuance records
+- recovery following a service interruption between registration and token
+ issuance
Definition of Done
==================
-(Only applicable to design documents that describe a new feature. While the
-DoD is not satisfied yet, a user-facing feature **must** be behind a feature
-flag or dev-mode flag.)
+- shares can be purchased using ordinary Taler digital cash
+- a successful purchase results in a registered shareholder position and in the
+ corresponding share tokens
+- transfers initiate a registration process and do not issue tokens to the
+ recipient before the registration succeeded
+- failed transfers do not create additional share tokens
+- a refresh replaces the previous token generation and pays the corresponding
+ dividend without changing the underlying share position
+- all operations can be audited and reconciled
+- the wallet and the merchant backend can recover safely from retries and
+ interruptions
Alternatives
============
@@ -129,14 +415,24 @@ Alternatives
it might make p2p transfers easier, but regulation on trading is
different for shares and the mismatch is likely big enough that
not overloading the exchange code with is it is a good idea.
-
-
+- Transferring bearer-style share tokens between wallets without a
+ registration step; this does not provide the synchronization between wallet
+ balances and the shareholder register that registered shares require.
Drawbacks
=========
+Open Questions
+==============
+
+The implementation must be reviewed against the applicable corporate-law and
+securities-law requirements before deployment. The design separates the
+technical representation of the shares from the shareholder register, but that
+separation alone does not establish the legal classification of the tokens or
+the regulatory status of the resulting system.
+
Discussion / Q&A
================
