Treasure Tracing Palace

A decentralized platform on Ethereum for product sales and traceability
📺View Demo »
English · 中文
Report An Issure · Submit Feature

Table of Contents

• About the Project📖
  • Feature Modules
    • Manufacturer 🏭
      • Create Product Type
      • Register Product Instance
      • Inventory Management
      • Order Management
      • Product Traceability
    • Distributor 🏪
      • Product Procurement
      • Inventory Management
      • Retail Products
      • Order Management
      • Product Traceability
    • Consumer 🛍️
      • Browse Products
      • Purchase Products
      • Order Management
      • Product Traceability
• Tech Stack ⚙️
  • Tools 🔧
  • Architecture 🏢
    • 🧩 1. Frontend Layer (User Interface Layer)
    • 🧠 2. Middleware Layer (Service Layer / API Layer)
    • 🗃 3. Database Layer (Data Persistence Layer)
    • ⛓ 4. Smart Contract Layer (Blockchain Layer)
    • ☁️ 5. Cloud Infrastructure Layer (DevOps & Deployment)
    • ✅ Summary
• Quick Start🚀
  • Clone Repository
  • 📦 Configure Environment Variables
    • 🔐 smart-contracts/.env
    • 🌐 front-end/.env
    • 🧪 front-end/.env.development
    • 🚀 front-end/.env.production
  • Development
    • Run IPFS Desktop
    • Run Local Database
    • Prisma Migration
    • Run Local Blockchain
    • Deploy Smart Contracts To Local Blockchain
    • Run Next.js Development Server
  • Production
    • Set Up Pinata
    • Deploy Smart Contracts To Sepolia
    • Prisma Migration
    • Next.js Build
    • Start Next.js Built Server
    • Publish Vercel
• Contribute 🧑🏿‍💻
  • Contributors❤️

About the Project📖

Treasure Tracing Palace is a decentralized supply chain platform built to help track and validate high-value products using blockchain. It drastically reduces counterfeit risk—for example, in pharmaceuticals and branded goods—by making every transaction transparent and verifiable.

Manufacturers register products in the system first. Products can then be sold to distributors at preset prices. Consumers can purchase from distributors, with all transactions recorded on-chain. Buyers can trace the full lifecycle of the product, from manufacture to delivery.

Our platform uses USDT as the payment currency.

Feature Modules

Manufacturer 🏭

Create Product Type

Register Product Instance

Inventory Management

Order Management

Product Traceability

Distributor 🏪

Product Procurement

Inventory Management

Retail Products

Order Management

Product Traceability

Consumer 🛍️

Browse Products

Purchase Products

Order Management

Product Traceability

(back to top)

Tech Stack ⚙️

Tools 🔧

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

Architecture 🏢

The overall layered architecture design of this project can be divided into the following six layers:

---

🧩 1. Frontend Layer (User Interface Layer)

Primarily responsible for building the user interaction interface. The tech stack includes:

• Next.js: A React framework used for server-side rendering (SSR) and static page generation.
• React: For building user interface components.
• Tailwind CSS: A utility-first CSS framework for quickly building beautiful UIs.
• Formik: For building complex forms and managing form state.
• RainbowKit & Wagmi: Used for wallet connection and Web3 wallet interactions.
• Ethers.js: For frontend interaction with Ethereum smart contracts.
• VSCode: Development tool.
• Lucide: Icon library that enhances the visual appeal of the UI.

➡️ This layer is mainly responsible for user interface display, wallet connection, and entry points for contract interaction.

---

🧠 2. Middleware Layer (Service Layer / API Layer)

• Node.js: Backend runtime environment that hosts API services.
• Prisma: ORM framework for connecting to the database, data modeling, and operations.
• Pino (represented by "Llama" in the diagram): High-performance logging tool.

➡️ This layer primarily handles data communication between frontend and backend, encapsulates database operations, and manages logging.

---

🗃 3. Database Layer (Data Persistence Layer)

• PostgreSQL: Relational database used to store structured data such as user info, product info, and order info.
• IPFS: Distributed storage system for storing immutable data like product images and certificates.

➡️ This layer supports queryable data persistence and decentralized storage for on-chain data.

---

⛓ 4. Smart Contract Layer (Blockchain Layer)

• Solidity: Programming language for developing smart contracts.
• Ethereum: Blockchain platform for deploying smart contracts.
• Hardhat: Tool for compiling, testing, and deploying contracts.
• MetaMask: Web3 wallet used for user signing and transactions.

➡️ This layer implements core on-chain logic, including product registration, order recording, and access control.

---

☁️ 5. Cloud Infrastructure Layer (DevOps & Deployment)

• Git: Version control for code.
• Vercel: Deployment platform for frontend services, supporting automated build and deployment.

➡️ Provides automated CI/CD for fast deployment, iteration, and testing.

---

✅ Summary

Layer	Main Responsibility	Technologies Used
Frontend Layer	User interaction & wallet connection	React, Next.js, Formik, Wagmi, etc.
Middleware Layer	API services & database operations	Node.js, Prisma
Database Layer	Structured data & distributed file storage	PostgreSQL, IPFS
Smart Contract Layer	Contract logic & blockchain interaction	Solidity, Ethereum, Hardhat
Cloud Infrastructure Layer	Auto deployment & continuous integration	Git, Vercel

---

(back to top)

Quick Start🚀

Clone Repository

git clone https://github.com/jingjiezhou2021/treasure-tracing-palace.git

📦 Configure Environment Variables

The project is divided into two workspaces: smart-contracts and front-end. Each workspace needs to set the environment variable configuration file. The following introduces each configuration item and its function

---

🔐 smart-contracts/.env

Variable Name	Description
ETHERSCAN_API_KEY	Used to interact with the Etherscan API after contract deployment for auto-verification
MNEMONIC	Wallet mnemonic phrase used to generate the private key for contract deployment
SEPOLIA_RPC_URL	RPC node address for the Sepolia testnet, used to connect to the blockchain network

---

🌐 front-end/.env

Variable Name	Description
AUTH_SECRET	Encryption key for user authentication
APP_DOMAIN	Domain address of the application
NEXTAUTH_URL	Service URL used by NextAuth.js
AUTH_TRUST_HOST	Trusted host setting for NextAuth
NEXTAUTH_SECRET	Key used to encrypt sessions and tokens (similar in function to AUTH_SECRET)

---

🧪 front-end/.env.development

Variable Name	Description
DATABASE_URL	PostgreSQL database connection string for development environment
PLATFORM_WALLET_PRIVATE_KEY	Private key used by the platform to initiate transactions
NEXT_PUBLIC_PLATFORM_WALLET_ADDR	Platform wallet address, visible to the frontend
NEXT_PUBLIC_USDT	USDT contract address (mock contract deployed locally)
NEXT_PUBLIC_PRODUCT_REGISTRY	Product management contract address
NEXT_PUBLIC_ORDER_REGISTRY	Order contract address
NEXT_PUBLIC_RPC_URL	RPC address of the local blockchain node
IPFS_RPC_URL	RPC address of the local IPFS node

---

🚀 front-end/.env.production

Variable Name	Description
DATABASE_URL	PostgreSQL database connection string for production
PLATFORM_WALLET_PRIVATE_KEY	Private key used by the platform to initiate on-chain transactions
NEXT_PUBLIC_PLATFORM_WALLET_ADDR	Platform wallet address (deployed on the Sepolia testnet)
NEXT_PUBLIC_USDT	USDT contract address (deployed on the Sepolia testnet)
NEXT_PUBLIC_PRODUCT_REGISTRY	Product registry contract address (deployed on the Sepolia testnet)
NEXT_PUBLIC_ORDER_REGISTRY	Order registry contract address (deployed on the Sepolia testnet)
NEXT_PUBLIC_RPC_URL	Blockchain testnet node address
PINATA_API_KEY	Pinata platform API key, used to upload files to IPFS
PINATA_API_SECRET	Pinata platform API secret
PINATA_JWT	JWT token used for authorized uploads via Pinata
NEXT_PUBLIC_PINATA_GATEWAY_URL	Pinata gateway URL (used on the frontend)
PINATA_GATEWAY_KEY	Authorization key for accessing the Pinata gateway

---

Development

Run IPFS Desktop

Check KURBO RPC API Address in the setting

SetIPFS_RPC_URL to KURBO RPC API Address in package/front-end/.env.development

IPFS_RPC_URL="/ip4/127.0.0.1/tcp/5001"

Run Local Database

In this repo I used Postgre SQL（If you're using another db please modify datasource.provider value in package/front-end/prisma/schema.prisma）

Set DATABASE_URL to the url of local database in package/front-end/.env.development

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE"

Prisma Migration

Local create git branch prisma-development

git checkout -b prisma-development

Reset to remote branch with the same name

git fetch --all
git reset --hard origin/prisma-development

Install dependencies

yarn

Change directory to packages/front-end

cd packages/front-end

Use prisma to reset database(Tap y to confirm action)

yarn dotenv -e .env.development -- yarn prisma migrate reset

Switch back to dev branch

git checkout dev

Reinstall the dependencies

yarn

Run Local Blockchain

Change directory to packages/smart-contract

cd ../smart-contract

Launch hardhat nodes

npx hardhat node

Launch successful

Deploy Smart Contracts To Local Blockchain

Create A New Console

Change directory to packages/smart-contract

cd packages/smart-contract

Execute deploying script

yarn dev-deploy

Deployment successful

The addresses of contracts are displayed in the log, copy paste these addresses into packages/front-end/.env.development

NEXT_PUBLIC_USDT= # USDT contract address
NEXT_PUBLIC_PRODUCT_REGISTRY= # ProductRegistry contract address
NEXT_PUBLIC_ORDER_REGISTRY= # OrderRegistry contract address

Run Next.js Development Server

Change directory to packages/front-end

cd ../front-end

Run dev script

yarn dev

Server started

Open localhost:3000 in the browser

To reach full capabilities of the project you need to configure Other Environment variables

Production

Set Up Pinata

Register account in Pinata Website

Enter account admin page

Copy gateway address into packages/front-end/.env.production,the name of key will be NEXT_PUBLIC_PINATA_GATEWAY_URL

NEXT_PUBLIC_PINATA_GATEWAY_URL= # pinata gateway address

Create gateway key

Copy gate way key into packages/front-end/.env.production,the name of key will be PINATA_GATEWAY_KEY

PINATA_GATEWAY_KEY= # pinata gateway key

Create an API key

Check admin option

Click Copy All to copy to clipboard

There are 3 parts in the copied content: API Key,API Secret,JWT

Create environment variables PINATA_API_KEY、PINATA_API_SECRET、PINATA_JWT inpackages/front-end/.env.production and paste the corresponding value for them

PINATA_API_KEY= # API Key value in the clipboard
PINATA_API_SECRET= # API Secret in the clipboard
PINATA_JWT= # JWT in the clipboard

Deploy Smart Contracts To Sepolia

Set the environment variables below in packages/smart-contract/.env

ETHERSCAN_API_KEY= # Etherscan API key
MNEMONIC= # Wallet mnemonic
SEPOLIA_RPC_URL= # Sepolia RPC node url

Change directory topackages/smart-contract

cd packages/smart-contract

Execute deploy to Sepolia script(tap y to confirm)

yarn deploy

Check contract in Etherscan tp see the contract has been verified

Prisma Migration

Set DATABASE_URLto url of the database used in production package/front-end/.env.production

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE"

Local create git branch prisma-production

git checkout -b prisma-production

Reset to remote branch with the same name

git fetch --all
git reset --hard origin/prisma-production

Install dependencies

yarn

Change directory to packages/front-end

cd packages/front-end

Use prisma to reset database(Tap y to confirm action)

yarn dotenv -e .env.production -- yarn prisma migrate reset

Switch back to dev

git checkout dev

Reinstall dependencies

yarn

Next.js Build

Change directory to packages/front-end

cd packages/front-end

Execute build script

yarn build

Build successful

Start Next.js Built Server

Run start script

yarn start

Open localhost:3000 in the browser

Publish Vercel

fork this repo

Register an account or login in Vercel Website

Create a new project

Choose the forked treasure-tracing-palace

Override build and install command

Copy package/front-end/.env,package/front-end/.env.production,package/smart-contract content and paste them into environment variables setting

Click deploy

After first deployment success you need to modify the values of NEXTAUTH_URL and AUTH_TRUST_HOST. First check the domain assigned by vercel

Set the values of both NEXTAUTH_URL,AUTH_TRUST_HOST to this domain

(back to top)

Contribute 🧑🏿‍💻

Contributing code is what makes the open source community a great place to learn, be inspired, and create. We really appreciate any contribution you may have.

If you have any suggestions for improvements, please fork the repository and create a pull request. You can also directly submit an issue with the "enhance" label.

Don't forget to give the project a star ⭐! Thanks again!

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Create a pull request

Contributors❤️

(back to top)