Solana Counter dApp Template

A beginner-friendly template for building applications (dApps) on Solana using Anchor and Next.js. This template implements a counter program that demonstrates essential Solana development concepts including PDAs (Program Derived Addresses), CPIs (Cross-Program Invocations), and state management.

demo.mp4

To try the demo, make sure to use a test wallet connected to devnet.

Phantom	Solflare
phantom.mp4	solflare.mp4

This template is for educational purposes and set up for devnet use only.

🎓 Educational Purpose

This template is designed for developers who want to learn:

• How to build Solana programs using the Anchor framework
• How to work with PDAs for state management and program signing
• How to perform Cross-Program Invocations (CPIs)
• How to create frontends that interact with Solana programs
• How to handle wallet connections and transactions on a frontend

📝 Program Overview

The Solana program in this template demonstrates several core concepts through a simple counter application:

Program Derived Addresses (PDAs)

1. Counter PDA

   • Stores the counter's current value
   • Derived using the seed "counter"
   • Global state accessible to all users
   • Automatically initialized on first increment

2. Vault PDA

   • Holds SOL tokens from user transactions
   • Derived using:
     • Seed "vault"
     • User's public key
   • Each user gets their own vault
   • Demonstrates using PDAs for CPI signing

Instructions

1. Increment

   • Increases counter value by 1
   • Performs CPI to transfer 0.001 SOL from user to vault
   • Creates counter PDA if it doesn't exist
   • Demonstrates:
     • PDA initialization
     • System program CPI for SOL transfer
     • State management

2. Decrement

   • Decreases counter value by 1
   • Performs CPI to transfer 0.001 SOL from vault back to user
   • Demonstrates:
     • PDA signing (vault)
     • System program CPI with PDA as signer

Cross-Program Invocations (CPIs)

The program demonstrates CPIs through SOL transfers:

• User → Vault (increment): Basic CPI to system program
• Vault → User (decrement): CPI with PDA signing

🏗 Project Structure

├── program/             # Solana program (smart contract)
│   ├── programs/        # Program source code
│   ├── tests/           # Program tests
│   └── Anchor.toml      # Anchor configuration
│
└── frontend/           # Next.js frontend
    ├── app/            # app router page and layout
    ├── components/     # React components
    └── anchor-idl/     # Program IDL

🔧 Core Features

1. Solana Program

   • Counter state management using PDA
   • Vault system using user-specific PDAs
   • SOL transfer demonstration using CPIs
   • PDA initialization and signing

2. Frontend Application

   • Wallet adapter integration
   • Real-time counter updates
   • Transaction toast notifications
   • UI with Tailwind CSS and shadcn/ui

🚀 Getting Started

Prerequisites

• Node.js 18+ and pnpm
• Rust and Solana CLI tools
• Anchor Framework

Installation

1. Clone the repository:

git clone <repository-url>

2. Install program dependencies:

cd program
pnpm install
anchor build
anchor keys sync
anchor build
anchor deploy

If Operation timed out happens during anchor deploy, you can also use other RPC endpoint by passing --provider.cluster <your-custom-rpc> or you can override provider.cluster in Anchor.toml

3. Install frontend dependencies:

cd frontend
pnpm install
cp ../program/idl/counter.json frontend/anchor-idl/idl.json
cp ../program/target/types/counter.ts frontend/anchor-idl/idl.ts
pnpm dev

Action cp is important, so that you won't access the program others may have deployed. You'll notice that if your initial counter value is not null or zero.

Development

1. Test the program:

cd program
anchor test

2. Run the frontend:

cd frontend
pnpm dev

💡 Learning Resources

Program (Smart Contract)

• program/programs/counter/src/lib.rs: Core program logic
  • Instruction handling
  • PDA creation and management
  • CPI implementation

Frontend Components

• frontend/components/counter/: Main dApp components
  • CounterDisplay.tsx: Real-time data updates
  • IncrementButton.tsx & DecrementButton.tsx: Transaction handling
  • WalletButton.tsx: Wallet adapter button

Custom Hooks

• frontend/components/counter/hooks/:
  • useProgram.tsx: Program initialization and wallet management
  • useTransactionToast.tsx: Transaction notification

🔍 Key Concepts Demonstrated

1. Program Development

   • PDA creation and management
     • Counter state PDA
     • User-specific vault PDAs
   • Cross-Program Invocations (CPIs)
     • Basic transfers (user to vault)
     • PDA signing (vault to user)
   • State management
     • Initialize-if-needed pattern
     • Program state updates

2. Frontend Development

   • Wallet integration and connection
   • Transaction building and signing
   • Account subscription for real-time updates
   • Toast notifications for transaction feedback