📚 LibrarySystem Smart Contract Suite

简体中文 | English

🇬🇧/🇺🇸 English README

📖 Project Information

This project is an affiliated outcome of the course
CSIT5760 (L1) - Blockchain and Smart Contracts
at The Hong Kong University of Science and Technology (HKUST).
It is submitted as one of the assignments (individual project) of the course.

Course Staff

Name	Role
Pritom Rajkhowa	Instructor & Teaching Assistant

🙌 Welcome

• Happy coding and smooth deployments 🚀
• Welcome to use this project
• According to the spirit of communism and open source, it is glad to share this project openly
• Hope you stay healthy, successful, and happy
• Hope your code always compiles, tests always pass, and deployments always succeed

✍️ Style Notes

• Concise bullet-point style, instead of long report/essay style
• No long essays or walls of text
• Each line short and direct
• Information modular and easy to scan
• Designed for developers and people here to quickly find what they need

🚀 Quick Start

• Install dependencies:

  forge install foundry-rs/forge-std
  forge install OpenZeppelin/openzeppelin-contracts

• Build contracts:

  forge build

• Run tests:

  forge test -vvvv

👀 Overview

• Smart contract system simulating library operations
• Components: LibrarySystem, MemberManagement, BookManagement, PointManagement
• Uses OpenZeppelin libraries and Foundry framework

🖥️ Requirements

• Foundry
• Python 3.8+
• Slither

📦 Dependencies

• forge-std
• openzeppelin-contracts

🧪 Testing

• Run all tests: forge test -vvvv
• Save logs: python3 script/shellScript/testAllGenerateLogTxt.py
• Logs saved under ./log/forgeTest/

🚀 Deployment

• Set environment variables:
  • SEPOLIA_RPC_URL
  • PRIVATE_KEY
  • ETHERSCAN_API_KEY
• Run script:

  bash ./script/deploymentScript/build_and_upload_to_testnet.sh

• Logs:
  • ./broadcast/DeployAll.s.sol/.../run-latest.json
  • ./script/deployment_logs.txt

🌐 Testnet Deployment (Sepolia)

This section shows the deployed contract addresses on the Sepolia testnet, with direct Etherscan verification links.

Contract	Address	Etherscan Link
BookManagement	0xc4d275FBB516FC2EE67892F1B515B6574b08a739	View
MemberManagement	0x6Cd93eF5B840E4aEA96e32483F4369591FF96484	View
PointManagement	0xb38Ef4a91eBABf3aCE3c96EBE666dA7B78e0F14c	View
LibrarySystem	0xF9268383D2E16DA5cb5d9e2928A02f363EFC449e	View

📂 Project Structure

• src/Contract/ → contracts
• src/Interface/ → interfaces
• src/Library/ → shared libraries
• test/ → tests
• script/ → deployment scripts
• log/ → logs [Not Created/Included in repo]

.
├── .github/
│   └── workflows/
│       └── test.yml
├── .gitignore
├── README.md
├── README.zh-CN.md
├── foundry.lock
├── foundry.toml
├── script/
│   ├── deploymentScript/
│   │   ├── DeployAll.s.sol
│   │   └── build_and_upload_to_testnet.sh
│   └── shellScript/
│       ├── slitherAllGenerateLogTxt.py
│       ├── testAllGenerateLogTxt.py
│       └── testAllGenerateLogTxt.xonsh
├── slither.config.json
├── src/
│   ├── Contract/
│   │   ├── BookManagement.sol
│   │   ├── LibrarySystem.sol
│   │   ├── MemberManagement.sol
│   │   └── PointManagement.sol
│   ├── Interface/
│   │   ├── IBookManagement.sol
│   │   ├── ILibrarySystem.sol
│   │   ├── IMemberManagement.sol
│   │   └── IPointManagement.sol
│   └── Library/
│       ├── CombinedChildContract.sol
│       └── StructSummary.sol
├── test/
│   ├── BookManagement.t.sol
│   ├── LibrarySystem.t.sol
│   ├── MemberManagement.t.sol
│   └── PointManagement.t.sol
├── .gitmodules
└── lib/
    ├── forge-std/
    └── openzeppelin-contracts/

🛡️ Security & Permissions

• Child contracts restricted via mainContract
• Admin addresses for initialization and upgrades

🔍 Slither Security Analysis

• Install: pip install slither-analyzer
• Run: python3 script/shellScript/slitherAllGenerateLogTxt.py
• Logs in ./log/slither/

▶️ Usage Example

librarySystem.registerMember("Alice");
librarySystem.borrowBook(1);
librarySystem.addPoints("Alice", 10);
librarySystem.redeemPoints("Alice", 5);

---

🔄 CI/CD

• GitHub Actions workflow runs tests on push
• Logs available in GitHub Actions and locally

❓ FAQ

• Test results → ./log/forgeTest/
• Security analysis → ./log/slither/
• Deployment issues → check RPC, gas, Foundry

📌 Version Info

• Solidity ^0.8.20 (contracts use 0.8.30)
• OpenZeppelin v5.x

🤝 Contributing

• Pull requests welcome
• For major changes, open an issue first

📜 License

• MIT License

---