This project demonstrates how to use the Solana Javascript API to 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 (v14 recommended)
- Install npm
- Install Rust v1.56.1 or later from https://rustup.rs/
- Install Solana v1.8.2 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.
If you're on Windows, it is recommended to use WSL to run these commands
- Set CLI config url to localhost cluster
solana config set --url localhost- Create CLI Keypair
If this is your first time using the Solana CLI, you will need to generate a new keypair:
solana-keygen newThis example connects to a local Solana cluster by default.
Start a local Solana cluster:
solana-test-validatorNote: You may need to do some system tuning (and restart your computer) to get the validator to run
Listen to transaction logs:
solana logsnpm 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-rustnpm run build:program-csolana program deploy dist/program/helloworld.sonpm run startPublic key values will differ:
Let's say hello to a Solana account...
Connection to cluster established: http://localhost:8899 { 'feature-set': 2045430982, 'solana-core': '1.7.8' }
Using account AiT1QgeYaK86Lf9kudqKthQPCWwpG8vFA1bAAioBoF4X containing 0.00141872 SOL to pay for fees
Using program Dro9uk45fxMcKWGb1eWALujbTssh6DW8mb4x8x3Eq5h6
Creating account 8MBmHtJvxpKdYhdw6yPpedp6X6y2U9dCpdYaZJdmwV3A to say hello to
Saying hello to 8MBmHtJvxpKdYhdw6yPpedp6X6y2U9dCpdYaZJdmwV3A
8MBmHtJvxpKdYhdw6yPpedp6X6y2U9dCpdYaZJdmwV3A has been greeted 1 times
Success- Ensure you've started the local cluster, built the on-chain program and deployed the program to the cluster.
- Inspect the program logs by running
solana logsto see why the program failed.-
Transaction executed in slot 5621: Signature: 4pya5iyvNfAZj9sVWHzByrxdKB84uA5sCxLceBwr9UyuETX2QwnKg56MgBKWSM4breVRzHmpb1EZQXFPPmJnEtsJ Status: Error processing Instruction 0: Program failed to complete Log Messages: Program G5bbS1ipWzqQhekkiCLn6u7Y1jJdnGK85ceSYLx2kKbA invoke [1] Program log: Hello World Rust program entrypoint Program G5bbS1ipWzqQhekkiCLn6u7Y1jJdnGK85ceSYLx2kKbA consumed 200000 of 200000 compute units Program failed to complete: exceeded maximum number of instructions allowed (200000) at instruction #334 Program G5bbS1ipWzqQhekkiCLn6u7Y1jJdnGK85ceSYLx2kKbA failed: Program failed to complete
-
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 and redeploy the 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 TypeScript using:
The client's entrypoint does five things.
The client establishes a connection with the cluster by calling
establishConnection.
The client ensures there is an account available to pay for transactions,
and creates one if there is not, by calling
establishPayer.
In checkProgram,
the client loads the keypair of the deployed program from ./dist/program/helloworld-keypair.json and uses
the public key for the keypair to fetch the program account. If the program doesn't exist, the client halts
with an error. If the program does exist, it will create a new account with the program assigned as its owner
to store program state (number of hello's processed).
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
reportGreetings.
The on-chain helloworld program is a Rust program compiled to Berkeley Packet Filter (BPF) bytecode 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 On-Chain 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 the Solana CLI to configure which cluster to connect to.
To point to devnet:
solana config set --url devnetTo point back to the local cluster:
solana config set --url localhostThis example details writing the client code in typescript; however the Solana client program can be written in any language. For an example client written in Rust and an accompanying write up see this repo.
There is lots more to learn; The following examples demonstrate more advanced features like custom errors, advanced account handling, suggestions for data serialization, benchmarking, etc...