Hello Solana (Anchor Rust + Java Client)

This project is a complete "Hello World" implementation on the Solana blockchain.

It features a smart contract (called program) built with the Anchor (Rust) framework and a modern client application written in Java using the Sol4k library.

The goal of this project is to demonstrate how to build a simple Solana program using Anchor and Sol4k, and to understand the basic concepts of Solana blockchain.

With this project, you will learn how to:

• Write a simple Solana program using Anchor and deploy it to the local blockchain using Surfpool.
• Interact with the Solana blockchain using Sol4k (store a message, read it, update it)
• Understand the basics of Solana accounts and transactions

Unlike Ethereum, Solana program does not store any state on the blockchain. Instead, it relies on the blockchain's distributed ledger to verify and execute transactions, ensuring high performance and scalability. In other words, when we write a message on chain, using this Solana program, we are creating a new storage account on the blockchain and storing the message in it. The program is the owner of this storage account, and it can only read and write to this account. This is a very simple example of a Solana program.

---

Goal of this project

The Solana program has three basic functions :

1. Store a message in a storage account
2. Read a message from a storage account
3. Update a message in a storage account

The Java client is a simple command-line application that interacts with the Solana blockchain, calling the Solana program to store, read and update messages.

By message, I mean a string...("hello world" or anything else but nothing fancy)

It is a good starting point for anyone looking to learn how to build a Solana program and interact with the blockchain.

---

Prerequisites

• Java 26
• Maven
• Surfpool (Solana Local Validator)
• Anchor CLI
• Solana CLI
• Solana Wallet

Project Architecture

On Solana, code and data are strictly separated:

• The Smart Contract (solana/programs/): Written in Rust, it acts as a read-only executable (a "robot"). It contains the logic to allocate storage space and write a message into it.
• The Storage Account (SolanaProgram.java): A dedicated account created dynamically at a unique public address to physically store the text string.
• The Java Client (SolanaClient.java): Instantiates the transaction, funds the storage space, triggers the smart contract to write the message, and finally reads back the raw bytes directly from the blockchain.

---

Quick Start Guide

Step 1: Start the Local Validator (Surfpool)

Open a dedicated terminal window and launch your local blockchain simulator: Note: Surfpool is a local validator that runs on your machine.

Note: Launch it from the solana directory of this project.

surfpool start

Note: Surfpool runs a local test environment (localhost) listening on port 8899.

Step 2: Build and Deploy the Smart Contract

Open a terminal window in the solana directory

1. Build the Rust code

anchor build

2. Deploy the binary to Surfpool

anchor deploy

Warning: As soon as the deployment succeeds, make sure to back up the program's private key file located at target/deploy/hello_solana-keypair.json. If you delete or clean the target/ directory without saving the key, you will permanently lose ownership of your program!

3. Run the Java client

The easiest way to run the application is directly through your IDE (e.g., IntelliJ IDEA):

1. Open the Java project in your IDE.
2. Verify that the programId in your code matches the newly deployed program.
3. Navigate to the main class: src/main/java/com/raph/application/Application.java.
4. Click the Run button (or right-click and select "Run 'Application.main()'").

---

Local State & Surfpool Volatility

Because Surfpool is an in-memory blockchain simulator, closing it (Ctrl+C) will wipe the ledger state and all your saved messages.

To handle this gracefully, the Java application features Persistent Local State:

• When a new message is created, its address is saved in a local storage_accounts.txt file.
• Upon startup, the Java client reads this file and verifies each address against the running Surfpool instance.
• If Surfpool was restarted and the data wiped, the Java client automatically cleans up its history, ensuring your local application remains perfectly synced with the blockchain.

---

Important note on programId

when we initialize the Solana program with anchor, anchor generates a programId.

However, on the first run on another computer, or if we delete the target/ directory without saving the key, the programId will be different that the one we have in the code. This is because a new cryptographic keypair is generated locally by Anchor during the build process when the target/ directory is missing. So, after building the program with anchor build, and then deploying it with anchor deploy, we will have a new programId printed in the console. Take this new programId and replace the one in the code (in the solana/src/lib.rs, the solana/Anchor.toml and src/main/java/SolanaProgram.java), and then rebuild and redeploy the solana program

Important note

Do not use this program for production or use as a template for production. It is not secure and should not be used in production. Care your private key!