Stock Tokenization Blockchain

This project is a simulation of a blockchain designed to manage the tokenization of real-world financial assets like stocks and bonds. It provides a backend API and a web-based UI to interact with a custom-built blockchain that features cryptographic security and the ability to perform corporate actions like paying dividends.

Starting the Lesson?
Check out the Complete Student Guide for step-by-step instructions on running the simulation, from initializing wallets to settling trades.

Core Features

• Custom Blockchain: Implemented from scratch in Python, featuring blocks, chains, and proof-of-work consensus.
• Persistent Database Layer (New):
  • MongoDB: Stores blockchain state (blocks, transactions, ledgers).
  • PostgreSQL: Stores user identity (KYC) and order book data.
• Asset Tokenization: Create and manage assets with rich metadata (e.g., stock tickers, bond maturity dates).
• Cryptographic Security: All transactions are secured using public/private key cryptography (ECDSA). Transactions must be signed by the asset owner.
• Client-Side Signing: The web UI handles all cryptographic operations (key generation and signing) directly in the browser.
• Smart Contracts (New):
  • Programmable Logic: Deploy and interact with smart contracts like Escrow and Voting.
  • Secure Simulation: Uses a restricted execution environment (simulated) for contract logic.
• Canton Network Domains (New):
  • Privacy & Scalability: Assets can reside on different domains (Global, Canton-US, Canton-EU).
  • Cross-Domain Transfers: Atomic movement of assets between domains.
• DTCC Clearing & Settlement (New):
  • On-Chain Netting: Trade intents are recorded on-chain, and a netting engine settles the net difference instantly (T-0).
  • Deposit-to-Trade: Simulation of real-world clearing house mechanics where assets must be deposited to the CCP domain before trading.
• Corporate Actions:
  • Dividend Payouts: Asset issuers can distribute payments to all current shareholders proportionally.
  • Stock Splits: Multiply all shares by a ratio (e.g., 2-for-1 split) across all shareholders.
  • Share Buybacks: Companies can repurchase shares from all holders proportionally at a specified price.
• Balance Checking: Query the balance of any asset for any wallet address.
• RESTful API & Web UI: A Flask-based API server exposes the blockchain functionality. The frontend is now a modern React application.

Project Structure

/
├── backend/
│   ├── app.py             # Flask API server
│   ├── blockchain.py      # Core Blockchain logic + Contract Engine
│   ├── contracts.py       # Smart Contract templates (Escrow, Voting)
│   ├── wallet.py          # Wallet class (ECDSA)
│   └── requirements.txt   # Python dependencies
└── frontend/            # React + Tailwind UI
    ├── src/               # React source code
    ├── public/            # Static assets
    └── package.json       # Node.js dependencies

---

Getting Started

1. Prerequisites (Databases)

This project requires MongoDB and PostgreSQL to be running locally.

1. MongoDB: Port 27017 (Default).
2. PostgreSQL: Port 5432 (Default). Database compliance_exchange will be auto-created.
   • Note: Update backend/.env if your Postgres credentials differ from the default.

2. Running the Backend

The backend is a Flask server that runs the blockchain logic.

1. Navigate to the backend directory:

   cd backend

2. Install the required Python dependencies:

   pip install -r requirements.txt

3. Run the Flask application:

   python app.py

The server will start on http://localhost:5001.

3. Running the Frontend

The frontend is a modern React application. You need Node.js installed.

1. Open a new, separate terminal.
2. Navigate to the frontend directory:

   cd frontend

3. Install dependencies (first time only):

   npm install

4. Start the development server:

   npm run dev

5. Open the link shown in the terminal (usually http://localhost:5173).

---

Smart Contracts Guide

Escrow

A standard escrow contract where funds are held until an arbiter releases them.

1. Deploy: Template Escrow. Args: {"arbiter": "PUBKEY", "beneficiary": "PUBKEY", "asset_name": "CASH", "amount": 50}.
2. Fund: Send CASH to the generated Contract Address using a standard Transfer.
3. Release: The Arbiter calls method release to send funds to the beneficiary.

Voting

A proposal-based voting system.

1. Deploy: Template Voting.
2. Create Proposal: Owner calls create_proposal with {"description": "Buy more servers"}.
3. Vote: Token holders call vote with {"proposal_id": "1"}. Voting weight is based on their GEM-STOCK balance.

Canton & DTCC Guide

Cross-Domain Transfers

Move assets between privacy domains (e.g., Global -> Canton-US).

1. Go to Market & Assets -> Transfer.
2. Enable Cross-Domain Transfer.
3. Select Source (Global) and Destination (Canton-US) domains.
4. The asset will disappear from the Global ledger and appear in the Canton-US private ledger.

DTCC T-0 Settlement

Simulate instant trade settlement via a clearing house.

1. Deposit: Move assets to the DTCC-Clearing domain (using Cross-Domain Transfer above).
2. Trade: Go to DTCC Clearing page and submit a SELL order.
3. Settle: Click Run Netting & Settle. The system calculates net obligations and settles them On-Chain in a single transaction.

---

🧐 Pedagogical Validity & Real-World Context

This simulation is designed to be a highly realistic representation of the Institutional Blockchain (Capital Markets) revolution currently occurring in the financial sector. It strips away "crypto hype" to focus on the structural efficiency gains that banks and regulators care about.

Concept in Simulation	Real-World Equivalent	Explanation
GSCOIN vs. CASH	JPM Coin / RLN	Banks do not settle in volatile crypto assets. They settle in Tokenized Deposits (Commercial Bank Money). The simulation's separation of "Value Tokens" (GSCOIN) from "Gas Tokens" (CASH) mirrors the Regulated Liability Network.
DTCC Domain (Netting)	Project Ion (DTCC)	The move from T+2 to T-0 Settlement is the biggest operational shift in finance. The simulation's netting engine demonstrates how blockchain can act as the "Golden Source of Truth" for clearing, eliminating reconciliation costs.
Atomic Swaps (DvP)	Canton Network	Delivery vs. Payment (DvP) without a central counterparty eliminates settlement risk (Herstatt Risk). This is the core value proposition of inter-bank ledger interoperability projects like Canton.
Collateralized Loans	Project Guardian	Institutions are piloting Intraday Repo markets where they tokenize Treasuries to borrow cash for hours. The simulation's "DeFi Lending" contract is a simplified model of these institutional credit facilities.

Verdict: This project teaches the workflows of a Digital Asset Architect at a Tier-1 Bank, rather than a retail crypto trader. It focuses on the three pillars of enterprise blockchain: Privacy (Domains), Finality (Settlement), and Interoperability (Atomic Swaps).