A proof of concept for onboarding GBP fixed-income assets, tokenising their principal, allocating tokens, calculating coupons, and processing maturity redemption.
Use Python 3.11 or newer.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
streamlit run app/main.pyBy default, BLOCKCHAIN_MODE=simulation. Simulated transaction references are
prefixed with sim:; they are not Ethereum transaction hashes and do not move
tokens or cash on a network. Data is stored in the versioned JSON files under
data/. Set DATA_DIR to use a different data directory.
The Dashboard offers Load demonstration bond scenario when the JSON store is empty and simulation mode is active. It creates a £10m, 5.25%, five-year corporate bond with a one-million-token cap and allocates 50,000, 100,000, and 250,000 tokens to Investors A, B, and C.
The checked-in JSON files are pre-populated with this demonstration state.
Their sim: references and token address are local simulation data, not
on-chain records. Before connecting to a testnet, use a fresh, empty data
directory (DATA_DIR) and onboard/issue assets on that network.
python -m unittest discover -s tests -vCompile the Solidity contracts with Solidity 0.8.24 and OpenZeppelin Contracts
5.x, deploy a GBP-denominated ERC-20 payment token with 2 decimals, then deploy
AssetRegistry and CouponManager:
npm install
npm run compile
$env:RPC_URL = "<testnet RPC endpoint>"
$env:CHAIN_ID = "<testnet chain id>"
$env:DEPLOYER_PRIVATE_KEY = "<operator key>"
$env:PAYMENT_TOKEN_ADDRESS = "<deployed GBP test token>"
npm run deploy:testnet
Set the AssetRegistry and CouponManager addresses printed by the deployment
script, then configure the Python application. Compiled artifacts are written
under artifacts/contracts/ and contain the ABI and bytecode consumed by
Web3.py:
BLOCKCHAIN_MODE=web3
RPC_URL=<testnet RPC endpoint>
CHAIN_ID=<testnet chain id>
DEPLOYER_PRIVATE_KEY=<operator key>
REGISTRY_ADDRESS=<deployed AssetRegistry>
REGISTRY_ARTIFACT_PATH=<absolute path to AssetRegistry.json>
TOKEN_ARTIFACT_PATH=<absolute path to BondToken.json>
COUPON_MANAGER_ADDRESS=<deployed CouponManager>
PAYMENT_TOKEN_ADDRESS=<deployed GBP test token>
The operator wallet must hold test-network gas and payment tokens. Before coupon processing, it must hold enough payment tokens; the application approves the CouponManager to transfer the calculated batch amount. The Python and Hardhat settings must point to the same testnet and operator. Use a dedicated test key and never commit keys or RPC credentials.
- Amounts are integer pence; coupon rates are basis points; token quantities are whole units with zero ERC-20 decimals.
- Periodic coupons use nominal annual rate divided by annual, semi-annual, or quarterly frequency, rounded to the nearest penny. Stub periods, day-count conventions, business-day calendars, tax, withholding, and settlement timing are not modeled.
- Coupon eligibility is reconstructed from confirmed allocation and burn events for the selected record date. For holdings loaded without transaction history, the current JSON holding is used as the available baseline.
- Redemption payout is an operator-confirmed off-chain action. The service records that confirmation and burns the investor's tokens; it does not send principal cash.
- JSON repository writes are atomic per file, but multi-file workflows cannot provide database transactions or distributed-chain atomicity. Pending and failed transaction records are retained for operator reconciliation. A pending operation blocks another operation of the same kind until an operator reconciles its on-chain and JSON state; the UI surfaces this error.
- This is demonstration software, not production custody, transfer-agent, compliance, or investment infrastructure. Review contracts and business controls before any deployment beyond a test environment.