Quickaro

Educational Prototype -- Simulated Delivery vs Payment (DvP) using smart contracts on a local Hardhat blockchain and on etherium sepolia testnet This project does not interact with real financial systems or real money.

https://drive.google.com/file/d/1yrDS5JShOH_2JlZr0zdEvxc2tmYH36tI/view?usp=sharing (demo link)

Project Structure

horizon/
├── contracts/
│   ├── AssetContract.sol      # ERC-20 BOND token (tokenized asset)
│   ├── PaymentToken.sol       # ERC-20 SET token (settlement currency)
│   └── SettlementEngine.sol   # DvP atomic settlement engine
├── scripts/
│   └── deploy.cjs             # Deploys contracts, mints demo tokens
├── backend/
│   ├── server.js              # Express API server
│   ├── blockchain.js          # ethers.js v6 setup (NonceManager) & contract instances
│   ├── deployment.json        # Auto-generated after deploy (contract addresses)
│   └── routes/
│       └── tradeRoutes.js     # Trade lifecycle API endpoints (Creates Terminal Logs)
├── frontend/
│   ├── index.html             # Dashboard UI (Blueprint Sketch Layout)
│   ├── style.css              # Pure CSS (Floating Island, Glassmorphism, Neon Dot)
│   └── app.js                 # API calls & DOM logic (Synced Role Switcher)
├── hardhat.config.cjs         # Hardhat config (local network)
├── package.json
└── README.md

---(this was for last hardhat version , sepolia testnet version are not reconfigurd here)

Core Technologies & Refinements

• Backend / Ethers v6: The backend connects to the local Hardhat node using Ethers.js v6. All signers are wrapped in ethers.NonceManager to automatically handle transaction nonces accurately under heavy load. Addresses from signers are fetched asynchronously via await getAddress() to prevent mapping errors.
• Frontend / Blueprint Sketch UI: The UI features a ultra-clean, hand-drawn "blueprint" aesthetic. Visual elements include a floating container island over a pure dark background, deep charcoal and slate blue hues, a sidebar with a dynamic "breathing" neon connectivity dot, and a 3-dot hover statistics menu utilizing glassmorphism (frosted glass) and SVG back-drop blurs.
• Terminal Settlement Receipts: When a trade successfully settles, a detailed receipt is printed directly in the backend Node.js terminal showing the exact timestamp and the remaining wallet balances for both the Buyer and Seller.

---

Setup Guide

Prerequisites

• Node.js v18 or later
• npm

Step 1 -- Install Dependencies

npm install

Step 2 -- Compile Smart Contracts

npm run compile

Step 3 -- Start the Local Blockchain Node

Open a new terminal and run:

npm run node

Keep this terminal open. This starts a local Hardhat blockchain at http://127.0.0.1:8545.

Step 4 -- Deploy Contracts & Mint Demo Tokens

In another terminal:

npm run deploy

This will:

• Deploy AssetContract (BOND), PaymentToken (SET), and SettlementEngine
• Mint 1000 BOND to the demo seller
• Mint 5000 SET to the demo buyer
• Write contract addresses to backend/deployment.json

Step 5 -- Start the Backend Server

npm run backend

Server runs at http://localhost:3001. Keep this window open to monitor trade lifecycle events and the detailed settlement receipts.

Step 6 -- Open the Frontend

Open your browser and navigate to:

http://localhost:3001

---

How to Use the Dashboard

Demo Accounts (Hardhat local network)

Role	Address	Initial Balance
Deployer	0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266	Admin
Buyer	0x70997970C51812dc3A010C7d01b50e0d17dc79C8	5000 SET
Seller	0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC	1000 BOND

Trade Lifecycle

1. Create Trade -- Fill in the seller address, BOND amount, SET amount, and click Create Trade. The buyer initiates the trade.
2. Confirm Trade -- Click Confirm on the trade row. The seller approves and confirms.
3. Settle Trade -- Click Settle. The smart contract atomically swaps BOND (seller->buyer) and SET (buyer->seller) in a single transaction.

Check the terminal window running npm run backend to see the transaction receipt and balance left-offs immediately following settlement.

---

API Endpoints

Method	Endpoint	Description
POST	/trade/create	Create a new trade
POST	/trade/confirm	Confirm a trade (seller)
POST	/trade/settle	Atomically settle a trade (DvP)
GET	/trade/list	List all trades from blockchain
GET	/portfolio/:addr	Get BOND & SET balances

---

Smart Contracts

SettlementEngine -- DvP Logic

settleTrade(tradeId)
  |- transferFrom(seller -> buyer, BOND amount)   <-- Asset delivery
  └- transferFrom(buyer  -> seller, SET amount)   <-- Payment
         ^ Both or neither -- atomic!

If either token transfer fails, the entire transaction reverts.

---

Safety Notice

• Runs entirely on a local Hardhat node -- no external network connections
• Uses demo tokens only (BOND, SET) -- no real monetary value
• Private keys used are the well-known Hardhat test keys -- never use these on a real network
• For educational and prototyping purposes only