Issue tokenized bonds

Manage the tokenized corporate bond lifecycle on Ethereum: subscription, coupon payments, and redemption, all secured by DFNS wallets and policies.

Issue tokenized corporate bonds on Ethereum where investors subscribe with stablecoins, receive ERC-20 bond tokens, collect periodic coupon payments, and redeem principal at maturity. All transactions signed through DFNS managed wallets.

Get the code

dfns/dfns-solutions: bond-issuance

Overview

The system models a bond issuance with two actors:

• Issuer: deploys the bond contract, manages the lifecycle (close issuance, fund coupons, return principal)
• Investor: subscribes with stablecoins, claims bond tokens, collects coupons, redeems at maturity

The bond lifecycle works as follows:

1. The Issuer deploys a stablecoin (EURC) and the Bond contract
2. Investors subscribe by depositing EURC into escrow
3. The Issuer closes the issuance. The interest accrual clock starts
4. Investors claim ERC-20 bond tokens proportional to their investment
5. Each coupon period, the Issuer funds and Investors claim their pro-rata share
6. At maturity, the Issuer deposits principal and Investors redeem bonds for EURC

Issuer (DFNS Wallet)                Bond Contract               Investor (DFNS Wallet)
       |                                  |                              |
       |-- deploy bond ----------------->|                              |
       |                                  |                              |
       |                                  |<--- approve + subscribe ----|
       |                                  |     EURC held in escrow      |
       |                                  |                              |
       |-- close issuance -------------->|                              |
       |-- withdraw proceeds ----------->|                              |
       |                                  |                              |
       |                                  |<--- claim bond -------------|
       |                                  |     ERC-20 tokens minted     |
       |                                  |                              |
       |-- deposit coupon (periodic) --->|                              |
       |                                  |<--- claim coupon -----------|
       |                                  |     pro-rata EURC payout     |
       |                                  |                              |
       |-- return principal ------------>|  (at maturity)               |
       |                                  |<--- redeem -----------------|
       |                                  |     bonds burned, EURC back  |

The contract also includes default protection: if the Issuer fails to fund a coupon within a 5-day grace period, anyone can trigger a default flag that halts further operations.

Component	Technology
Contracts	Solidity 0.8.28 (OpenZeppelin, Hardhat v3)
Signing	DFNS KMS via @dfns/sdk
Scripts	TypeScript (tsx, viem)
Web UI	Single-page Express app with split Issuer/Investor dashboards
Stablecoin	ERC-20 with mint/burn/pause (6 decimals)
Network	Ethereum Sepolia

Prerequisites

• A DFNS account with a service account for API access
• Two DFNS wallets on Ethereum Sepolia (Issuer and Investor)
• Node.js v22+
• Testnet ETH in both wallets for gas fees (use a Sepolia faucet)

Project Structure

contracts/
  Bond.sol              ERC-20 bond token with full lifecycle management
  BondMath.sol          Library for accrued interest calculation
  StableCoin.sol        ERC-20 stablecoin with mint, burn, pause, and roles

scripts/
  dfns.ts               Shared DFNS API client and viem public client
  server.ts             Express server with REST API for the web UI
  ui.html               Single-page web UI (Issuer + Investor dashboards)
  e2e.ts                Non-interactive end-to-end lifecycle script
  deploy-stablecoin.ts  Deploy a stablecoin contract
  deploy-bond.ts        Deploy a bond contract with configurable terms
  mint-stablecoin.ts    Mint stablecoin to any address
  issuer-ops.ts         Interactive CLI for issuer operations
  holder-ops.ts         Interactive CLI for investor operations
  stablecoin-ops.ts     Interactive CLI for stablecoin management

test/
  Bond.test.ts          Core lifecycle tests
  BondExtended.test.ts  Over/under-subscription, grace period, interest math
  BondFull.test.ts      Full lifecycle with 4 investors
  BondSpecific.test.ts  Short-duration bond scenario

Configuration

1. Clone and install

   git clone https://github.com/dfns/dfns-solutions.git
   cd dfns-solutions/bond-issuance
   npm install
   
2. Set up environment variables

   Copy the example environment file and fill in your values:

   cp .env.example .env
   

   .env

   # DFNS API Configuration
   DFNS_API_URL=https://api.dfns.io
   DFNS_ORG_ID=or-xxx-xxx
   DFNS_AUTH_TOKEN=eyJ...
   DFNS_CRED_ID=cred-xxx
   DFNS_PRIVATE_KEY="-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----"
   
   # DFNS Wallet IDs
   ISSUER_WALLET_ID=wa-xxx-xxx
   INVESTOR_WALLET_ID=wa-xxx-xxx
   
   # Blockchain Configuration (optional)
   SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
   

   Variable	Description
   DFNS_API_URL	DFNS API base URL (api.dfns.io)
   DFNS_ORG_ID	Your DFNS organization ID. See how to locate it.
   DFNS_AUTH_TOKEN	Service account auth token. Refer to creating a service account.
   DFNS_CRED_ID	Credential ID for the service account signing key. Find it on the dashboard, on the Service Account page.
   DFNS_PRIVATE_KEY	Service account private key for request signing (PEM format, including the ----BEGIN/END PRIVATE KEY----)
   ISSUER_WALLET_ID	Wallet ID for the bond issuer (wa-xxxx...)
   INVESTOR_WALLET_ID	Wallet ID for the bond investor (wa-xxxx...)
   SEPOLIA_RPC_URL	RPC endpoint (defaults to public Sepolia endpoint if omitted)

3. Compile contracts

   npm run compile
   
4. Run tests

   The test suite runs against a local Hardhat network (no DFNS credentials needed):

   npm test
   

   16 tests cover the full lifecycle: subscription, over/under-subscription, coupon claims, redemption, grace periods, default triggering, and interest math.

Deploy

Step 1: Deploy the stablecoin

npm run deploy:stablecoin

The script prompts for a name and symbol (defaults to “Euro Coin” / “EURC”) and deploys from the Issuer wallet. Save the contract address.

Step 2: Mint stablecoin to the investor

npm run mint:stablecoin

Enter the stablecoin address, the investor’s wallet address, and the amount to mint.

Step 3: Deploy the bond

npm run deploy:bond

The script prompts for bond parameters:

Parameter	Default	Description
Name	Corporate Bond	Bond token name
Symbol	CB	Bond token symbol
Currency	none	Stablecoin contract address (required)
Notional	100	Face value per bond in stablecoin units
APR	400 (4%)	Annual rate in basis points
Coupon Frequency	7,776,000 (3 months)	Seconds between coupon periods
Duration	31,536,000 (1 year)	Seconds until maturity
Cap	1,000,000	Maximum stablecoin to raise

Save the bond contract address.

End-to-End Bond Lifecycle

Step 1: Investor subscribes

npm run ops:holder
# Select option 2: Subscribe
# Enter the subscription amount in stablecoin units

This approves the Bond contract to spend the investor’s EURC, then calls subscribe(). The stablecoin is held in escrow.

Step 2: Issuer closes issuance

npm run ops:issuer
# Select option 2: Close Issuance

This locks the subscription total, starts the interest accrual clock, and calculates the coupon amount per period.

Step 3: Issuer withdraws proceeds

npm run ops:issuer
# Select option 3: Withdraw Proceeds

The issuer receives the raised stablecoin.

Step 4: Investor claims bond tokens

npm run ops:holder
# Select option 3: Claim Bond

The investor receives ERC-20 bond tokens. The number of tokens is calculated as:

bondTokens = (investmentAmount * 10^decimals) / notional

Where decimals is 6 (matching the stablecoin).

Step 5: Coupon payments (each period)

Issuer deposits the coupon:

npm run ops:issuer
# Select option 5: Deposit Coupon

The required amount is calculated automatically: (totalPrincipal * APR * frequency) / (365 days * 10000).

Investor claims:

npm run ops:holder
# Select option 4: Claim Coupon

The CLI auto-detects all due, funded, unclaimed coupons and claims them in sequence. Each investor’s share is proportional to their bond holdings:

share = (userBalance / totalSupply) * couponAmount

Step 6: Redemption at maturity

Issuer returns principal:

npm run ops:issuer
# Select option 4: Return Principal

Investor redeems:

npm run ops:holder
# Select option 5: Redeem

Bond tokens are burned and the original investment amount is returned in EURC.

Web UI

The browser UI covers the full bond lifecycle. It shows two dashboards side by side, Issuer (blue) and Investor (green), with numbered steps to follow in order.

npm run ui

Open http://localhost:3000. The UI calls a lightweight Express server that signs and broadcasts transactions via the DFNS API. Bond status auto-refreshes every 5 seconds.

Each step in the UI maps to a contract function call:

1. Deploy StableCoin: deploy the EURC contract
2. Mint EURC: fund both wallets
3. Deploy Bond: configure face value, APR, coupon frequency, and duration
4. Subscribe: investor deposits EURC into escrow
5. Close Issuance: lock subscriptions, start interest clock
6. Withdraw Proceeds: issuer collects raised EURC
7. Claim Bond Tokens: investor mints ERC-20 bond tokens
8. Deposit Coupon: issuer funds the next coupon period
9. Claim Coupon: investor collects pro-rata interest (auto-detects coupon index)
10. Return Principal: issuer deposits EURC for redemption
11. Redeem: investor burns bonds, gets principal back

End-to-End Script

Run the full lifecycle non-interactively:

npm run e2e

This deploys both contracts, mints stablecoins, subscribes, closes issuance, claims bonds, deposits and claims a coupon, all in a single run. Useful for verifying the setup end to end.

Smart Contract Reference

Bond.sol

An ERC-20 token representing a corporate bond with full lifecycle management:

Function	Caller	Description
subscribe(amount)	Investor	Deposit stablecoin into escrow during issuance
closePrimaryIssuance()	Issuer	Lock subscriptions, start interest clock
withdrawProceeds()	Issuer	Withdraw raised stablecoin
claimBond()	Investor	Mint bond tokens proportional to subscription
depositCoupon()	Issuer	Fund the next coupon period
claimCoupon(index)	Investor	Claim pro-rata coupon payment
returnPrincipal(amount)	Issuer	Deposit stablecoin for redemption
redeem()	Investor	Burn bonds, receive principal
checkDefault(index)	Anyone	Trigger default if coupon unfunded past grace period
accruedInterest(user)	View	Real-time accrued interest for a holder
timeToNextCoupon()	View	Seconds until the next coupon date

Bond lifecycle: Open → Issuance Closed → Coupons → Maturity / Redemption

Default path: Coupon Due → Grace Period (5 days) → Default

BondMath.sol

Library for interest calculations:

Accrued = (principal * APR * timeElapsed) / (365 days * 10000)

APR is in basis points (400 = 4%). The contract treats a year as exactly 365 days.

StableCoin.sol

ERC-20 stablecoin used as the settlement currency:

Feature	Implementation
Standard	ERC-20 with 6 decimals (matching USDC/EURC convention)
Minting	Role-based via MINTER_ROLE, only authorized addresses can mint
Burning	Any holder can burn their own tokens via ERC20Burnable
Pausing	Owner can pause/unpause all transfers
Permits	ERC-2612 gasless approvals via ERC20Permit
Access control	OpenZeppelin AccessControl for role management

How DFNS Is Used

All on-chain transactions are signed and broadcast through the DFNS API. No private keys are stored locally.

Operation	DFNS SDK call
Get wallet address	wallets.getWallet({ walletId })
Deploy contract	wallets.broadcastTransaction({ walletId, body: { kind: "Evm", data: encodedBytecode } })
Call contract function	wallets.broadcastTransaction({ walletId, body: { kind: "Evm", to: address, data: encodedCalldata } })

The scripts use viem to encode deployment data and function calldata, then broadcast via DFNS. A viem PublicClient reads on-chain state (balances, bond status, coupon dates) without requiring signing.

Adapting for Production

Different networks: Replace the RPC URL in .env with one for your target network (Ethereum mainnet, Polygon, Arbitrum). Update the chain import in scripts/dfns.ts.

Real stablecoins: Replace the demo StableCoin contract with USDC or EURC addresses. The Bond contract accepts any ERC-20 with 6 decimals as the settlement currency.

Multiple investors. The system supports any number of investors. Each uses a separate DFNS wallet. Add more wallet IDs to .env or build a backend that maps users to DFNS wallets (see the accept cryptocurrencies blueprint for this pattern).

Secondary trading: Bond tokens are standard ERC-20 and can be traded on any DEX. For institutional use, consider an RFQ model (UniswapX or CowSwap) where professional market makers provide quotes based on yield-to-maturity.

Approval policies: DFNS policies can enforce approval quorums or velocity limits on sensitive operations (closing issuance, large coupon deposits). This adds governance without changing the smart contracts.