CredChain — Blockchain-Verified Credentials

CredChain is a decentralized certificate issuance platform built on the Stellar Soroban smart contract platform. Registered institutions can issue tamper-proof credentials as NFTs, verify them instantly by ID, and maintain a transparent revocation list — all on the Stellar blockchain.

Live Demo & Deployment Info

• Live Demo URL: https://credchain-stellar.vercel.app
• Deployed Contract Address: CBMYQYSWFPCXG5B5WXC73P4V6WR765EGA2YSMMSNM32I47Q4YYAQDXFE
• Successful Contract Call Tx Hash: 872a109b7bf635750440c9ba1a6444127205126e88254761d7c7beb300980ec1 (Stellar Testnet)

System Architecture

graph TD
    Client[Next.js Client] -->|Reads / Writes| RPC[Soroban RPC Server]
    Client -->|XLM Transfers| Horizon[Stellar Horizon API]
    Client -->|Connects & Signs| SWK[Stellar Wallets Kit]
    SWK -->|Integrates| Freighter[Freighter Wallet]
    SWK -->|Integrates| xBull[xBull Wallet]
    SWK -->|Integrates| Albedo[Albedo Wallet]
    RPC -->|Interacts| Contract[CredChain Soroban Contract]
    Contract -->|Inter-Contract Call| Token[Stellar Asset Token Contract]
    RPC -->|Emits Events| Client

Loading

---

Features

• 🏛️ Institution Registration — Register as a verified institution on-chain.
• 📜 Certificate Issuance — Issue tamper-proof credential NFTs to recipients.
• ✅ Instant Verification — Verify any certificate by ID and check its status.
• ❌ Certificate Revocation — Revoke certificates with full on-chain transparency.
• 💸 Send XLM — Transfer XLM directly on the Stellar Testnet.
• 🔄 Real-Time Event Listening — Automatic UI updates and toast notifications using RPC contract event polling.
• 🌙 Dark Mode — Sleek dark/light theme toggle.
• 🔌 Multi-Wallet Support — Integrated via Stellar Wallets Kit (Freighter, xBull, Albedo).

---

Tech Stack

• Smart Contract: Rust + Soroban SDK
• Frontend: Next.js 15 + TypeScript
• Styling: Tailwind CSS + shadcn/ui
• State: Zustand + TanStack Query
• Blockchain: Stellar Soroban + @stellar/stellar-sdk
• Wallet Integration: @creit.tech/stellar-wallets-kit

---

Folder Structure

credchain/
├── contract/                     # Soroban smart contract
│   ├── Cargo.toml
│   ├── src/
│   │   ├── lib.rs            # Contract implementation
│   │   └── test.rs           # Contract tests
│   └── Makefile              # Build rules
├── client/                       # Next.js frontend
│   ├── src/
│   │   ├── app/                  # Pages
│   │   │   ├── page.tsx          # Landing page
│   │   │   ├── dashboard/        # Wallet, Send XLM & institution overview
│   │   │   ├── app/              # Main application (Issuance & Revocation)
│   │   │   └── activity/         # Event feed & transactions history
│   │   ├── components/           # UI components
│   │   │   ├── ui/               # UI primitives
│   │   │   ├── Navbar.tsx
│   │   │   ├── WalletModal.tsx
│   │   │   ├── ActivityFeed.tsx
│   │   │   └── TransactionTracker.tsx
│   │   ├── hooks/                # Custom hooks
│   │   │   ├── contract.ts       # TanStack Query contract read/write hooks
│   │   │   ├── useContractEventsListener.ts # Real-time Soroban RPC event poller
│   │   │   └── use-toast.ts
│   │   ├── stores/               # Zustand stores
│   │   │   ├── wallet.ts         # Wallet state & transaction actions
│   │   │   ├── transactions.ts   # UI transaction tracking
│   │   │   └── activity.ts       # Activity events
│   │   ├── lib/                  # Utilities
│   │   │   ├── utils.ts
│   │   │   ├── contracts.ts      # Network config
│   │   │   └── scval.ts          # ScVal converters
│   │   └── types/                # TypeScript types
│   ├── .env.example              # Env template
│   └── scripts/deploy.sh         # Deployment script
└── README.md

---

Setup & Run Instructions

Prerequisites

• Rust (stable)
• Node.js 18+
• Stellar CLI (installed and on PATH)
• Freighter, xBull, or Albedo browser extension wallet

Environment Variables

Copy client/.env.example to client/.env and update the variables:

cd client
cp .env.example .env

NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_CONTRACT_ADDRESS=CBMYQYSWFPCXG5B5WXC73P4V6WR765EGA2YSMMSNM32I47Q4YYAQDXFE

Local Development

1. Install dependencies:

   cd client
   npm install

2. Start the development server:

   npm run dev

3. Open http://localhost:3000 in your browser.

---

Smart Contract Build & Deployment

If you want to compile and deploy the contract yourself:

# Navigate to contract directory
cd contract

# Build the contract target
stellar contract build

# Deploy to Testnet
stellar contract deploy \
  --wasm target/wasm32v1-none/release/credchain.wasm \
  --source dev \
  --network testnet

---

Testing

Smart Contract Tests

Run unit tests for the smart contract (including mock token fee inter-contract calls):

cd contract
cargo test

Frontend Tests

Run unit tests for the client-side XDR helper utilities:

cd client
npm run test

---

CI/CD Pipeline & GitHub Actions

This project features a GitHub Actions workflow configured in .github/workflows/ci.yml. On every push and pull request to the main branch, the workflow:

1. Sets up the Rust toolchain and installs components (rustfmt, clippy).
2. Checks Rust contract formatting (cargo fmt --check).
3. Runs Rust static code analysis and linting (cargo clippy -- -D warnings).
4. Runs all 18 contract unit tests (cargo test).
5. Builds the contract WASM target (wasm32v1-none).
6. Installs frontend Node dependencies.
7. Runs frontend code linting and style checks (npm run lint).
8. Runs all 24 frontend unit tests (npm run test).
9. Performs Next.js production compilation to verify build soundness.

---

Working States & Screenshots

1. Wallet Connected State

The application supports connecting to multiple Stellar wallets (Freighter, xBull, Albedo). Once connected, the user's wallet address and status are displayed in the dashboard.

2. Balance Displayed

The wallet balance (retrieved directly from the Stellar Horizon network) is displayed dynamically in the Wallet Status card.

3. Successful Testnet Transaction

Users can send XLM transfers directly on the Stellar Testnet. When a transaction is submitted, the transaction is signed using the connected wallet and broadcasted to the network.

4. Transaction Result Displayed

The real-time status of the transaction (pending, success, or failure) is shown to the user with detailed feedback and a direct link to view it on the Stellar Explorer.

5. Mobile Responsive UI

The frontend has been verified on mobile, tablet, and desktop viewports to ensure clean layouts and smooth wallet interactions.

6. CI/CD Workflow Pipeline

The automated GitHub Actions workflow executes building, linting, formatting, and unit testing on every push and pull request.

7. Automated Test Output

All 18 smart contract tests and 24 frontend store/utility tests pass successfully.

---

Future Improvements

1. IPFS Metadata Pinning: Automatically pin certificate metadata to IPFS/Arweave from the client side during issuance.
2. Batch Issuance: Optimize the contract and frontend to support issuing multiple certificates to different recipients in a single transaction.
3. Advanced Role Access: Implement multi-signature roles to allow multiple staff members to authorize certificate revocations.
4. CSV/Excel Recipient Import: Allow upload of CSV lists of recipients to automatically generate certificates in bulk.

---

Stellar Mastery Verification Checklist

✅ Wallet Connect — Supports connecting via multiple wallets. ✅ Wallet Disconnect — Clean disconnect and state clearing. ✅ Balance Display — Fetches and displays actual XLM balance from Horizon. ✅ Testnet Transaction — Send XLM on Testnet directly in the dApp. ✅ Error Handling — Handles wallet-not-installed, user-rejections, and insufficient-balances. ✅ Multi-wallet Support — Handled via @creit.tech/stellar-wallets-kit. ✅ Smart Contract Deployed — Deployed at CBMYQYSWFPCXG5B5WXC73P4V6WR765EGA2YSMMSNM32I47Q4YYAQDXFE. ✅ Frontend Contract Calls — Fully integrated read/write interactions. ✅ Contract Read — Checks institution status and verifies certificates. ✅ Contract Write — Register institutions, issue, and revoke certificates. ✅ Event Listener & Real-Time Sync Indicator — Real-time event polling, query cache invalidation, and live sync status badge in the Navbar. ✅ Smart Contract Input Validation — Added safety checks rejecting empty inputs with custom InvalidInput errors. ✅ Robust Testing — 18 smart contract unit tests and 24 frontend store/utility tests passing successfully. ✅ CI/CD Pipeline Checks — Automated Rust formatting, clippy static analysis, and Next.js ESLint linting in GitHub Actions. ✅ Transaction Status — Clear display of Pending, Success, and Failed states. ✅ 10+ Meaningful Git Commits — Grouped logically in Git history. ✅ Public GitHub Repository — Pushed and accessible on GitHub. ✅ README Complete — Fully detailed documentation with Mermaid architecture diagram. ✅ Live Demo — Deployed and running on Vercel. ✅ Demo Video Link — CredChain Level 3 Presentation Video (1-2 mins)