This project demonstrates how to use the Solana Javascript API to build, deploy, and interact with programs on the Solana blockchain.
The project comprises of:
- An on-chain hello world program
- A client that can send a "hello" to an account and get back the number of times "hello" has been sent
- Hello world on Solana
If you decide to open in Gitpod then refer to README-gitpod.md, otherwise continue reading.
The following dependencies are required to build and run this example, depending on your OS, they may already be installed:
- Install node
- Install npm
- Install the latest Rust stable from https://rustup.rs/
- Install Solana v1.5.8 or later from https://docs.solana.com/cli/install-solana-cli-tools
If this is your first time using Rust, these Installation Notes might be helpful.
This example connects to a local Solana cluster by default.
Enable on-chain program logs:
$ export RUST_LOG=solana_runtime::system_instruction_processor=trace,solana_runtime::message_processor=debug,solana_bpf_loader=debug,solana_rbpf=debugStart a local Solana cluster:
$ solana-test-validator --log$ npm installThere is both a Rust and C version of the on-chain program, whichever is built last will be the one used when running the example.
$ npm run build:program-rust$ npm run build:program-c$ npm run startPublic key values will differ:
Lets say hello to a Solana account...
Connection to cluster established: http://localhost:8899 { solana-core: 1.1.2 }
Loading hello world program...
Program loaded to account 47bZX1D1tdmw3KWTo5MfBrAwwHBJQQzQL4VnNGT7HtyQ
Creating account Eys1jdLHdZ2AE56QAKpfadbjziMZ6NAvpL7qsdtM6sbk to say hello to
Saying hello to Eys1jdLHdZ2AE56QAKpfadbjziMZ6NAvpL7qsdtM6sbk
Eys1jdLHdZ2AE56QAKpfadbjziMZ6NAvpL7qsdtM6sbk has been greeted 1 times
Success- Ensure you've started the local cluster and built the on-chain program.
- The cluster output log should include program log messages that indicate why
the program failed.
program log: <message>
- Inspect the Solana cluster logs looking for any failed transactions or failed
on-chain programs
- Expand the log filter and restart the cluster to see more detail
-
$ export RUST_LOG=solana_runtime::native_loader=trace,solana_runtime::system_instruction_processor=trace,solana_runtime::bank=debug,solana_bpf_loader=debug,solana_rbpf=debug $ solana-test-validator --log
-
- Expand the log filter and restart the cluster to see more detail
To customize the example, make changes to the files under /src. If you change
any files under /src/program-rust or /src/program-c you will need to
rebuild the on-chain program
Now when you rerun npm run start, you should see the results of your changes.
More information about how Solana works is available in the Solana documentation and all the source code is available on github
Further questions? Visit us on Discord
The client in this example is written in JavaScript using:
The client's entrypoint does four things
The client establishes a connection with the cluster by calling
establishConnection.
The process of loading a program on the cluster includes storing the shared object's bytes in a Solana account's data vector and marking the account executable.
The client loads the program by calling
loadProgram.
The first time loadProgram is called, the client:
- Reads the shared object from the file system
- Calculates the fees associated with loading the program
- Airdrops lamports to a payer account to pay for the load
- Loads the program via the Solana web3.js function 'BPFLoader.load'
- Creates a new "greeter" account that will be used in the "Hello" transaction
- Records the public
key
of both the loaded helloworld program and the "greeter" account in a config
file. Repeated calls to the client will refer to the same loaded program and
"greeter" account. (To force the reload of the program issue
npm clean:store)
The client then constructs and sends a "Hello" transaction to the program by
calling
sayHello.
The transaction contains a single very simple instruction that primarily carries
the public key of the helloworld program account to call and the "greeter"
account to which the client wishes to say "Hello" to.
Each time the client says "Hello" to an account, the program increments a
numerical count in the "greeter" account's data. The client queries the
"greeter" account's data to discover the current number of times the account has
been greeted by calling
reportHellos
The on-chain helloworld program is a Rust program compiled to Berkley Packet Format (BPF) and stored as an Executable and Linkable Format (ELF) shared object.
The program is written using:
To learn more about Solana programming model refer to the Programming Model Overview.
To learn more about developing programs on Solana refer to the Deployed Programs Overview
Solana maintains three public clusters:
devnet- Development cluster with airdrops enabledtestnet- Tour De Sol test cluster without airdrops enabledmainnet-beta- Main cluster
Use npm scripts to configure which cluster.
To point to devnet:
$ npm run cluster:devnetTo point back to the local cluster:
$ npm run cluster:localnetThere is lots more to learn; The following examples demonstrate more advanced features like custom errors, advanced account handling, suggestions for data serialization, benchmarking, etc...