[docs] quickstart guides (#27592)
* feat(wip): rust quickstart page * feat: added quickstart pages * fix: updated cards and card layout * feat: added quickstart home (and to sidebar ) * fix: updated quickstarts * fix: renamed to get started * fix: typos and seo * fix: JS example to interact with the onchain program
This commit is contained in:
Nick Frostbutter
GitHub
parent
ced8f6a512
commit
cf1c44184c
|
|
@ -4,7 +4,7 @@ import Link from "@docusaurus/Link";
|
|||
import styles from "../src/pages/styles.module.css";
|
||||
import Translate from "@docusaurus/Translate";
|
||||
|
||||
function Card({ to, header, body }) {
|
||||
function Card({ to, header, body, externalIcon = false }) {
|
||||
/*
|
||||
Both the `header` and `body` expect an object with the following type
|
||||
header = {
|
||||
|
|
@ -21,6 +21,20 @@ function Card({ to, header, body }) {
|
|||
<Translate description={header.translateId}>
|
||||
{header.label}
|
||||
</Translate>
|
||||
{externalIcon && (
|
||||
<svg
|
||||
width="13.5"
|
||||
height="13.5"
|
||||
aria-hidden="true"
|
||||
viewBox="0 0 24 24"
|
||||
className={styles.iconExternalIcon}
|
||||
>
|
||||
<path
|
||||
fill="currentColor"
|
||||
d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"
|
||||
></path>
|
||||
</svg>
|
||||
)}
|
||||
</h3>
|
||||
</div>
|
||||
<div className="card__body">
|
||||
|
|
|
|||
|
|
@ -20,6 +20,7 @@ function CardLayout({
|
|||
if (sidebarItems[key]?.type?.toLowerCase() === "category") {
|
||||
for (let i = 0; i < sidebarItems[key]?.items?.length; i++)
|
||||
sidebarItems[key].items[i] = formatter(sidebarItems[key].items[i]);
|
||||
sidebarItems[key].collapsed = true;
|
||||
} else sidebarItems[key] = formatter(sidebarItems[key]);
|
||||
});
|
||||
}
|
||||
|
|
@ -63,6 +64,7 @@ const formatter = (item) => {
|
|||
label: computeLabel(item) || item || "[unknown label]",
|
||||
};
|
||||
}
|
||||
|
||||
// handle object style docs
|
||||
else if (item?.type?.toLowerCase() === "doc") {
|
||||
item.type = "link";
|
||||
|
|
@ -71,5 +73,15 @@ const formatter = (item) => {
|
|||
delete item.id;
|
||||
}
|
||||
|
||||
// fix for local routing that does not specify starting at the site root
|
||||
if (
|
||||
!(
|
||||
item?.href.startsWith("/") ||
|
||||
item?.href.startsWith("http:") ||
|
||||
item?.href.startsWith("https")
|
||||
)
|
||||
)
|
||||
item.href = `/${item?.href}`;
|
||||
|
||||
return item;
|
||||
};
|
||||
|
|
|
|||
|
|
@ -83,18 +83,48 @@ module.exports = {
|
|||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Getting Started",
|
||||
label: "Get Started",
|
||||
items: [
|
||||
{
|
||||
type: "doc",
|
||||
id: "developing/intro/programs",
|
||||
label: "What are Programs?",
|
||||
type: "link",
|
||||
href: "/getstarted",
|
||||
label: "All guides",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "developing/intro/rent",
|
||||
label: "What is Rent?",
|
||||
id: "getstarted/hello-world",
|
||||
label: "Hello world",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "getstarted/local",
|
||||
label: "Local development",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "getstarted/rust",
|
||||
label: "Rust program",
|
||||
},
|
||||
// {
|
||||
// type: "doc",
|
||||
// id: "getstarted/token",
|
||||
// label: "Create a token",
|
||||
// },
|
||||
// {
|
||||
// type: "doc",
|
||||
// id: "getstarted/nft",
|
||||
// label: "Create a NFT",
|
||||
// },
|
||||
// {
|
||||
// type: "doc",
|
||||
// id: "getstarted/c",
|
||||
// label: "C / C++",
|
||||
// },
|
||||
// {
|
||||
// type: "doc",
|
||||
// id: "getstarted/web3js",
|
||||
// label: "Web3.js",
|
||||
// },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
@ -102,6 +132,11 @@ module.exports = {
|
|||
label: "Core Concepts",
|
||||
// collapsed: false,
|
||||
items: [
|
||||
{
|
||||
type: "doc",
|
||||
id: "developing/programming-model/accounts",
|
||||
label: "Accounts",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "developing/programming-model/transactions",
|
||||
|
|
@ -109,8 +144,13 @@ module.exports = {
|
|||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "developing/programming-model/accounts",
|
||||
label: "Accounts",
|
||||
id: "developing/intro/programs",
|
||||
label: "Programs",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "developing/intro/rent",
|
||||
label: "Rent",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
|
|
|
|||
|
|
@ -44,6 +44,18 @@ main {
|
|||
padding: 0 var(--ifm-pre-padding);
|
||||
}
|
||||
|
||||
.button {
|
||||
background-color: var(--ifm-link-color);
|
||||
color: var(--ifm-background-surface-color) !important;
|
||||
padding: 0.5em 0.8em;
|
||||
border: 0px solid red;
|
||||
font-size: 1em !important;
|
||||
}
|
||||
|
||||
.container__spacer {
|
||||
margin: 0em 1em 3em 1em;
|
||||
}
|
||||
|
||||
.cards__container {
|
||||
margin: 3em 0;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,287 @@
|
|||
---
|
||||
title: "Hello World Quickstart Guide"
|
||||
description: 'This "hello world" quickstart guide will demonstrate how to setup, build, and deploy your first Solana program in your browser with Solana Playground.'
|
||||
keywords: "playground, solana pg, on chain, rust, native program, tutorial, intro to solana development, blockchain developer, blockchain tutorial, web3 developer"
|
||||
---
|
||||
|
||||
For this "hello world" quickstart guide, we will use [Solana Playground](https://beta.solpg.io), a browser the based IDE, to develop and deploy our Solana program. To use it, you do **NOT** have to install any software on your computer. Simply open Solana Playground in your browser of choice, and you are ready to write and deploy Solana programs.
|
||||
|
||||
## What you will learn
|
||||
|
||||
- How to get started with Solana Playground
|
||||
- How to create a Solana wallet on Playground
|
||||
- How to program a basic Solana program in Rust
|
||||
- How to build and deploy a Solana Rust program
|
||||
- How to interact with your on chain program using JavaScript
|
||||
|
||||
## Using Solana Playground
|
||||
|
||||
[Solana Playground](https://beta.solpg.io) is browser based application that will let you write, build, and deploy on chain Solana programs. All from your browser. No installation needed.
|
||||
|
||||
It is a great developer resources for getting started with Solana development, especially on Windows.
|
||||
|
||||
### Import our example project
|
||||
|
||||
In a new tab in your browser, open our example "_Hello World_" project on Solana Playground: https://beta.solpg.io/6314a69688a7fca897ad7d1d
|
||||
|
||||
Next, import the project into your local workspace by clicking the "**Import**" icon and naming your project `hello_world`.
|
||||
|
||||
|
||||
|
||||
> If you do **not** import the program into **your** Solana Playground, then you will **not** be able to make changes to the code. But you **will** still be able to build and deploy the code to a Solana cluster.
|
||||
|
||||
### Create a Playground wallet
|
||||
|
||||
Normally with [local development](./local.md), you will need to create a file system wallet for use with the Solana CLI. But with the Solana Playground, you only need to click a few buttons to create a browser based wallet.
|
||||
|
||||
> **Note:**
|
||||
> Your _Playground Wallet_ will be saved in your browser's local storage. Clearing your browser cache will remove your saved wallet. When creating a new wallet, you will have the option to save a local copy of your wallet's keypair file.
|
||||
|
||||
Click on the red status indicator button at the bottom left of the screen, (optionally) save your wallet's keypair file to your computer for backup, then click "**Continue**".
|
||||
|
||||
After your Playground Wallet is created, you will notice the bottom of the window now states your wallet's address, your SOL balance, and the Solana cluster you are connected to (Devnet is usually the default/recommended, but a "localhost" [test validator](./local.md) is also acceptable).
|
||||
|
||||
## Create a Solana program
|
||||
|
||||
The code for your Rust based Solana program will live in your `src/lib.rs` file. Inside `src/lib.rs` you will be able to import your Rust crates and define your logic. Open your `src/lib.rs` file within Solana Playground.
|
||||
|
||||
### Import the `solana_program` crate
|
||||
|
||||
At the top of `lib.rs`, we import the `solana-program` crate and bring our needed items into the local namespace:
|
||||
|
||||
```rust
|
||||
use solana_program::{
|
||||
account_info::AccountInfo,
|
||||
entrypoint,
|
||||
entrypoint::ProgramResult,
|
||||
pubkey::Pubkey,
|
||||
msg,
|
||||
};
|
||||
```
|
||||
|
||||
### Write your program logic
|
||||
|
||||
Every Solana program must define an `entrypoint` that tells the Solana runtime where to start executing your on chain code. Your program's [entrypoint](../developing/on-chain-programs/developing-rust#program-entrypoint) should provide a public function named `process_instruction`:
|
||||
|
||||
```rust
|
||||
// declare and export the program's entrypoint
|
||||
entrypoint!(process_instruction);
|
||||
|
||||
// program entrypoint's implementation
|
||||
pub fn process_instruction(
|
||||
program_id: &Pubkey,
|
||||
accounts: &[AccountInfo],
|
||||
instruction_data: &[u8]
|
||||
) -> ProgramResult {
|
||||
// log a message to the blockchain
|
||||
msg!("Hello, world!");
|
||||
|
||||
// gracefully exit the program
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Every on chain program should return the `Ok` [result enum](https://doc.rust-lang.org/std/result/) with a value of `()`. This tells the Solana runtime that your program executed successfully without errors.
|
||||
|
||||
Our program above will simply [log a message](../developing/on-chain-programs/debugging#logging) of "_Hello, world!_" to the blockchain cluster, then gracefully exit with `Ok(())`.
|
||||
|
||||
### Build your program
|
||||
|
||||
On the left sidebar, select the "**Build & Deploy**" tab. Next, click the "Build" button.
|
||||
|
||||
If you look at the Playground's terminal, you should see your Solana program begin to compile. Once complete, you will see a success message.
|
||||
|
||||
|
||||
|
||||
> Note:
|
||||
> You may receive _warning_ when your program is compiled due to unused variables. Don't worry, these warning will not affect your build. They are due to our very simple program not using all the variables we declared in the `process_instruction` function.
|
||||
|
||||
### Deploy your program
|
||||
|
||||
You can click the "Deploy" button to deploy your first program to the Solana blockchain. Specifically to your selected cluster (e.g. Devnet, Testnet, etc).
|
||||
|
||||
After each deployment, you will see your Playground Wallet balance change. By default, Solana Playground will automatically request SOL airdrops on your behalf to ensure your wallet has enough SOL to cover the cost of deployment.
|
||||
|
||||
|
||||
|
||||
### Find your program id
|
||||
|
||||
When executing a program using [web3.js](../developing/clients/javascript-reference.md) or from [another Solana program](../developing/programming-model/calling-between-programs.md), you will need to provide the `program id` (aka public address of your program).
|
||||
|
||||
Inside Solana Playground's **Build & Deploy** sidebar, you can find your `program id` under the **Program Credentials** dropdown.
|
||||
|
||||
#### Congratulations!
|
||||
|
||||
You have successfully setup, built, and deployed a Solana program using the Rust language directly in your browser. Next, we will demonstrate how to interact with your on chain program.
|
||||
|
||||
## Interact with your on chain program
|
||||
|
||||
Once you have successfully deployed a Solana program to the blockchain, you will want to be able to interact with that program.
|
||||
|
||||
Like most developers creating dApps and websites, we will interact with our on chain program using JavaScript inside a NodeJS application. Specifically, will use the open source [NPM package](https://www.npmjs.com/package/@solana/web3.js) `@solana/web3.js` to aid in our client application.
|
||||
|
||||
> **NOTE:**
|
||||
> This web3.js package is an abstraction layer on top of the [JSON RPC API](./../developing/clients/jsonrpc-api.md) that reduced the need for rewriting common boilerplate, helping to simplify your client side application code.
|
||||
|
||||
### Initialize a new Node project
|
||||
|
||||
For a simple client application for our on chain program, create a new folder for the Node project to live:
|
||||
|
||||
```bash
|
||||
mkdir hello_world && cd hello_world
|
||||
```
|
||||
|
||||
Initialize a new Node project on you local computer:
|
||||
|
||||
```bash
|
||||
npm init -y
|
||||
# or
|
||||
yarn init -y
|
||||
```
|
||||
|
||||
To easily interact with the Solana blockchain, add the [`@solana/web3.js`](../developing/clients/javascript-api.md) package to your Node project:
|
||||
|
||||
```bash
|
||||
npm i @solana/web3.js
|
||||
# or
|
||||
yarn add @solana/web3.js
|
||||
```
|
||||
|
||||
Create a new file named `app.js` and open it in your favorite code editor. This is where we will work for the rest of our `hello world` program.
|
||||
|
||||
### Connect to the cluster
|
||||
|
||||
Import the `@solana/web3.js` library into your project so we can use all the JSON RPC helper functions that are built into it:
|
||||
|
||||
```js
|
||||
// import the Solana web3.js library
|
||||
const web3 = require("@solana/web3.js");
|
||||
```
|
||||
|
||||
We will also define the `SOLANA_CLUSTER` your program was deployed as well as the `PROGRAM_ID` of your new program:
|
||||
|
||||
```js
|
||||
// define our program ID and cluster to interact with
|
||||
const SOLANA_CLUSTER = "devnet";
|
||||
const PROGRAM_ID = "5AQaXHRKmoZMuBem544ELfEAN2qe2y9PU8nnezvpgeP7";
|
||||
```
|
||||
|
||||
Next we will need to create a `connection` to the specific cluster we deployed our program to:
|
||||
|
||||
```js
|
||||
// create a new connection to the Solana blockchain
|
||||
const connection = new web3.Connection(web3.clusterApiUrl(SOLANA_CLUSTER));
|
||||
```
|
||||
|
||||
### Create and fund a wallet for testing
|
||||
|
||||
In order to submit [transactions](../developing/programming-model/transactions.md) to a Solana cluster, you will need to have a wallet that will pay for the cost of execution. For simplicity, we will generate a dummy "throw away" wallet (and fund it with SOL) for our sample `hello_world` program named `payer`
|
||||
|
||||
```js
|
||||
// create a "throw away" wallet for testing
|
||||
let payer = web3.Keypair.generate();
|
||||
console.log("Generated payer address:", payer.publicKey.toBase58());
|
||||
|
||||
// fund the "throw away" wallet via an airdrop
|
||||
console.log("Requesting airdrop...");
|
||||
let airdropSignature = await connection.requestAirdrop(
|
||||
payer.publicKey,
|
||||
web3.LAMPORTS_PER_SOL,
|
||||
);
|
||||
|
||||
// wait for the airdrop to be completed
|
||||
await connection.confirmTransaction(airdropSignature);
|
||||
|
||||
// log the signature to the console
|
||||
console.log(
|
||||
"Airdrop submitted:",
|
||||
`https://explorer.solana.com/tx/${airdropSignature}?cluster=${SOLANA_CLUSTER}`,
|
||||
);
|
||||
```
|
||||
|
||||
> You will notice that we are logging a URL of the Solana Explorer to the console. This will help us view our transaction on the blockchain when we run our Node application.
|
||||
|
||||
### Create and send a transaction
|
||||
|
||||
To execute your on chain program, you must send a [transaction](../developing/programming-model/transactions.md) to it. Each transaction submitted to the Solana blockchain contains a listing of instructions (and the program's that instruction will interact with).
|
||||
|
||||
Here we create a new transaction and add a single `instruction` to it:
|
||||
|
||||
```js
|
||||
// create an empty transaction
|
||||
const transaction = new web3.Transaction();
|
||||
|
||||
// add a single instruction to the transaction
|
||||
transaction.add(
|
||||
new web3.TransactionInstruction({
|
||||
keys: [
|
||||
{
|
||||
pubkey: payer.publicKey,
|
||||
isSigner: true,
|
||||
isWritable: false,
|
||||
},
|
||||
{
|
||||
pubkey: web3.SystemProgram.programId,
|
||||
isSigner: false,
|
||||
isWritable: false,
|
||||
},
|
||||
],
|
||||
programId: new web3.PublicKey(PROGRAM_ID),
|
||||
}),
|
||||
);
|
||||
```
|
||||
|
||||
Each `instruction` must include all the keys involved in the operation and the program ID we want to execute. In this example, our `keys` contain the `payer` (that we created earlier to pay for the execution) and the [System Program](../developing/runtime-facilities/programs#system-program) (which is required for all program execution).
|
||||
|
||||
With our transaction created, we can submit it to the cluster (via our `connection`):
|
||||
|
||||
```js
|
||||
// submit the transaction to the cluster
|
||||
console.log("Sending transaction...");
|
||||
let txid = await web3.sendAndConfirmTransaction(connection, transaction, [
|
||||
payer,
|
||||
]);
|
||||
console.log(
|
||||
"Transaction submitted:",
|
||||
`https://explorer.solana.com/tx/${txid}?cluster=${SOLANA_CLUSTER}`,
|
||||
);
|
||||
```
|
||||
|
||||
### Run our application
|
||||
|
||||
With our Node application written, you can run the code via the command line:
|
||||
|
||||
```bash
|
||||
node app.js
|
||||
```
|
||||
|
||||
Once your Node application completes, you will see output similar to this:
|
||||
|
||||
```bash
|
||||
Generated payer address: 8fBnnMz2SLBcmrsrvWBAt91kSPAWRTkjbrVPJqDcxq2s
|
||||
Requesting airdrop...
|
||||
Airdrop complete: https://explorer.solana.com/tx/38EXqADsgAj1yNpcTDRwC66HooW1d9mk9PMnPP9V8JbsokZPuWZhP3W9EaixXhPFoBXVQk1NQ2otCs5W1ukt73Hc?cluster=devnet
|
||||
Sending transaction...
|
||||
Transaction submitted: https://explorer.solana.com/tx/3gv6uAkyDoLZR94hcMf3fDiwnDNN9rrdXos9rmMmok2xJtaW9NKehYKqSspxVH2HpAK7WHfRYQfsyuzr9gguzf2j?cluster=devnet
|
||||
```
|
||||
|
||||
> View this example transaction on Solana explorer: https://explorer.solana.com/tx/3gv6uAkyDoLZR94hcMf3fDiwnDNN9rrdXos9rmMmok2xJtaW9NKehYKqSspxVH2HpAK7WHfRYQfsyuzr9gguzf2j?cluster=devnet
|
||||
|
||||
Using the Solana explorer link for your "submitted transaction", you can view the message our program logged on chain, via `msg!("Hello, world!")`, in the "**Program Instruction Logs**" section of the Solana Explorer.
|
||||
|
||||
|
||||
|
||||
#### Congratulations!!!
|
||||
|
||||
You have now written a client application for your on chain program. You are now a Solana developer!
|
||||
|
||||
PS: Try to update your program's message then re-build, re-deploy, and re-execute your program.
|
||||
|
||||
## Next steps
|
||||
|
||||
See the links below to learn more about writing Solana programs:
|
||||
|
||||
- [Setup your local development environment](./local.md)
|
||||
- [Overview of writing Solana programs](../developing/on-chain-programs/overview)
|
||||
- [Learn more about developing Solana programs with Rust](../developing/on-chain-programs/developing-Rust)
|
||||
- [Debugging on chain programs](../developing/on-chain-programs/debugging)
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
---
|
||||
title: "Local Development Quickstart"
|
||||
description: "This quickstart guide will demonstrate how to quickly install and setup your local Solana development environment."
|
||||
keywords: "rust, cargo, toml, program, tutorial, intro to solana development, blockchain developer, blockchain tutorial, web3 developer"
|
||||
---
|
||||
|
||||
This quickstart guide will demonstrate how to quickly install and setup your local development environment, getting you ready to start developing and deploying Solana programs to the blockchain.
|
||||
|
||||
## What you will learn
|
||||
|
||||
- How to install the Solana CLI locally
|
||||
- How to setup a localhost Solana cluster/validator
|
||||
- How to create a Solana wallet for developing
|
||||
- How to airdrop SOL tokens for your wallet
|
||||
|
||||
## Install the Solana CLI
|
||||
|
||||
To interact with the Solana clusters from your terminal, install the [Solana CLI tool suite](../../cli/install-solana-cli-tools) on your local system:
|
||||
|
||||
```bash
|
||||
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"
|
||||
```
|
||||
|
||||
## Setup a localhost blockchain cluster
|
||||
|
||||
The Solana CLI comes with the [test validator](./../developing/test-validator.md) built in. This command line tool will allow you to run a full blockchain cluster on your machine.
|
||||
|
||||
```bash
|
||||
solana-test-validator
|
||||
```
|
||||
|
||||
> **PRO TIP:**
|
||||
> Run the Solana test validator in a new/separate terminal window that will remain open. The command line program must remain running for your localhost cluster to remain online and ready for action.
|
||||
|
||||
Configure your Solana CLI to use your localhost validator for all your future terminal commands:
|
||||
|
||||
```bash
|
||||
solana config set --url localhost
|
||||
```
|
||||
|
||||
At any time, you can view your current Solana CLI configuration settings:
|
||||
|
||||
```bash
|
||||
solana config get
|
||||
```
|
||||
|
||||
## Create a file system wallet
|
||||
|
||||
To deploy a program with Solana CLI, you will need a Solana wallet with SOL tokens to pay for the cost of transactions.
|
||||
|
||||
Let's create a simple file system wallet for testing:
|
||||
|
||||
```bash
|
||||
solana-keygen new
|
||||
```
|
||||
|
||||
By default, the `solana-keygen` command will create a new file system wallet located at `~/.config/solana/id.json`. You can manually specify the output file location using the `--outfile /path` option.
|
||||
|
||||
> **NOTE:**
|
||||
> If you already have a file system wallet saved at the default location, this command will **NOT** override it (unless you explicitly force override using the `--force` flag).
|
||||
|
||||
#### Set your new wallet as default
|
||||
|
||||
With your new file system wallet created, you must tell the Solana CLI to use this wallet to deploy and take ownership of your on chain program:
|
||||
|
||||
```bash
|
||||
solana config set -k ~/.config/solana/id.json
|
||||
```
|
||||
|
||||
## Airdrop SOL tokens to your wallet
|
||||
|
||||
Once your new wallet is set as the default, you can request a free airdrop of SOL tokens to it:
|
||||
|
||||
```bash
|
||||
solana airdrop 2
|
||||
```
|
||||
|
||||
> **NOTE:**
|
||||
> The `solana airdrop` command has a limit of how many SOL tokens can be requested _per airdrop_ for each cluster (localhost, testnet, or devent). If your airdrop transaction fails, lower your airdrop request quantity and try again.
|
||||
|
||||
You can check your current wallet's SOL balance any time:
|
||||
|
||||
```bash
|
||||
solana balance
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
See the links below to learn more about writing Rust based Solana programs:
|
||||
|
||||
- [Create and deploy a Solana Rust program](./rust.md)
|
||||
- [Overview of writing Solana programs](../developing/on-chain-programs/overview)
|
||||
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
title: "Rust Program Quickstart"
|
||||
description: "This quickstart guide will demonstrate how to quickly setup, build, and deploy your first Rust based Solana program to the blockchain."
|
||||
keywords: "rust, cargo, toml, program, tutorial, intro to solana development, blockchain developer, blockchain tutorial, web3 developer"
|
||||
---
|
||||
|
||||
Rust is the most common programming language to write Solana programs with. This quickstart guide will demonstrate how to quickly setup, build, and deploy your first Rust based Solana program to the blockchain.
|
||||
|
||||
> **NOTE: **
|
||||
> This guide uses the Solana CLI and assumes you have setup your local development environment. Checkout our [local development quickstart guide](./local.md) here to quickly get setup.
|
||||
|
||||
## What you will learn
|
||||
|
||||
- How to install the Rust language locally
|
||||
- How to initialize a new Solana Rust program
|
||||
- How to code a basic Solana program in Rust
|
||||
- How to build and deploy your Rust program
|
||||
|
||||
## Install Rust and Cargo
|
||||
|
||||
To be able to compile Rust based Solana programs, install the Rust language and Cargo (the Rust package manager) using [Rustup](https://rustup.rs/):
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
## Run your localhost validator
|
||||
|
||||
The Solana CLI comes with the [test validator](../developing/test-validator.md) built in. This command line tool will allow you to run a full blockchain cluster on your machine.
|
||||
|
||||
```bash
|
||||
solana-test-validator
|
||||
```
|
||||
|
||||
> **PRO TIP:**
|
||||
> Run the Solana test validator in a new/separate terminal window that will remain open. This command line program must remain running for your localhost validator to remain online and ready for action.
|
||||
|
||||
Configure your Solana CLI to use your localhost validator for all your future terminal commands and Solana program deployment:
|
||||
|
||||
```bash
|
||||
solana config set --url localhost
|
||||
```
|
||||
|
||||
## Create a new Rust library with Cargo
|
||||
|
||||
Solana programs written in Rust are _libraries_ which are compiled to [BPF bytecode](../developing/on-chain-programs/overview#berkeley-packet-filter-bpf) and saved in the `.so` format.
|
||||
|
||||
Initialize a new Rust library named `hello_world` via the Cargo command line:
|
||||
|
||||
```bash
|
||||
cargo init hello_world --lib
|
||||
cd hello_world
|
||||
```
|
||||
|
||||
Add the `solana-program` crate to your new Rust library:
|
||||
|
||||
```bash
|
||||
cargo add solana-program
|
||||
```
|
||||
|
||||
Open your `Cargo.toml` file and add these required Rust library configuration settings, updating your project name as appropriate:
|
||||
|
||||
```toml
|
||||
[lib]
|
||||
name = "hello_world"
|
||||
crate-type = ["cdylib", "lib"]
|
||||
```
|
||||
|
||||
## Create your first Solana program
|
||||
|
||||
The code for your Rust based Solana program will live in your `src/lib.rs` file. Inside `src/lib.rs` you will be able to import your Rust crates and define your logic. Open your `src/lib.rs` file in your favorite editor.
|
||||
|
||||
At the top of `lib.rs`, import the `solana-program` crate and bring our needed items into the local namespace:
|
||||
|
||||
```rust
|
||||
use solana_program::{
|
||||
account_info::AccountInfo,
|
||||
entrypoint,
|
||||
entrypoint::ProgramResult,
|
||||
pubkey::Pubkey,
|
||||
msg,
|
||||
};
|
||||
```
|
||||
|
||||
Every Solana program must define an `entrypoint` that tells the Solana runtime where to start executing your on chain code. Your program's [entrypoint](../developing/on-chain-programs/developing-rust#program-entrypoint) should provide a public function named `process_instruction`:
|
||||
|
||||
```rust
|
||||
// declare and export the program's entrypoint
|
||||
entrypoint!(process_instruction);
|
||||
|
||||
// program entrypoint's implementation
|
||||
pub fn process_instruction(
|
||||
program_id: &Pubkey,
|
||||
accounts: &[AccountInfo],
|
||||
instruction_data: &[u8]
|
||||
) -> ProgramResult {
|
||||
// log a message to the blockchain
|
||||
msg!("Hello, world!");
|
||||
|
||||
// gracefully exit the program
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Every on chain program should return the `Ok` [result enum](https://doc.rust-lang.org/std/result/) with a value of `()`. This tells the Solana runtime that your program executed successfully without errors.
|
||||
|
||||
This program above will simply [log a message](../developing/on-chain-programs/debugging#logging) of "_Hello, world!_" to the blockchain cluster, then gracefully exit with `Ok(())`.
|
||||
|
||||
## Build your Rust program
|
||||
|
||||
Inside a terminal window, you can build your Solana Rust program by running in the root of your project (i.e. the directory with your `Cargo.toml` file):
|
||||
|
||||
```bash
|
||||
cargo build-bpf
|
||||
```
|
||||
|
||||
> **NOTE:**
|
||||
> After each time you build your Solana program, the above command will output the build path of your compiled program's `.so` file and the default keyfile that will be used for the program's address.
|
||||
|
||||
## Deploy your Solana program
|
||||
|
||||
Using the Solana CLI, you can deploy your program to your currently selected cluster:
|
||||
|
||||
```bash
|
||||
solana program deploy ./target/deploy/hello_world.so
|
||||
```
|
||||
|
||||
Once your Solana program has been deployed (and the transaction [finalized](../cluster/commitments.md)), the above command will output your program's public address (aka its "program id").
|
||||
|
||||
```bash
|
||||
# example output
|
||||
Program Id: EFH95fWg49vkFNbAdw9vy75tM7sWZ2hQbTTUmuACGip3
|
||||
```
|
||||
|
||||
#### Congratulations!
|
||||
|
||||
You have successfully setup, built, and deployed a Solana program using the Rust language.
|
||||
|
||||
> PS: Check your Solana wallet's balance again after you deployed. See how much SOL it cost to deploy your simple program?
|
||||
|
||||
## Next steps
|
||||
|
||||
See the links below to learn more about writing Rust based Solana programs:
|
||||
|
||||
- [Overview of writing Solana programs](../developing/on-chain-programs/overview)
|
||||
- [Learn more about developing Solana programs with Rust](../developing/on-chain-programs/developing-Rust)
|
||||
- [Debugging on chain programs](../developing/on-chain-programs/debugging)
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
import React from "react";
|
||||
import Link from "@docusaurus/Link";
|
||||
import styles from "./styles.module.css";
|
||||
import Card from "../../components/Card";
|
||||
import CardLayout from "../../layouts/CardLayout";
|
||||
|
|
@ -13,14 +14,29 @@ function Developers() {
|
|||
>
|
||||
<section className={styles.features}>
|
||||
<div className="container">
|
||||
<section>
|
||||
<h1>Learn Solana Development</h1>
|
||||
|
||||
<div className="container__spacer">
|
||||
<p>
|
||||
Build and deploy your first on chain Solana program directly in
|
||||
your browser.
|
||||
</p>
|
||||
|
||||
<Link to="/getstarted/hello-world">
|
||||
<a className="button">Get Started</a>
|
||||
</Link>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="">
|
||||
<h2>Learn Solana development</h2>
|
||||
<h2>Learn core concepts</h2>
|
||||
|
||||
<div className="row cards__container">
|
||||
<Card
|
||||
to="developing/intro/programs"
|
||||
header={{
|
||||
label: "Getting Started",
|
||||
label: "Programs",
|
||||
translateId: "developer-programs",
|
||||
}}
|
||||
body={{
|
||||
|
|
|
|||
|
|
@ -0,0 +1,126 @@
|
|||
import React from "react";
|
||||
import Link from "@docusaurus/Link";
|
||||
import styles from "./styles.module.css";
|
||||
import Card from "../../components/Card";
|
||||
import CardLayout from "../../layouts/CardLayout";
|
||||
|
||||
function GetStartedPage() {
|
||||
return (
|
||||
<CardLayout
|
||||
sidebarKey="developerSidebar"
|
||||
title="Developer Quick Start Guides"
|
||||
description="Solana Documentation"
|
||||
path="/getstarted"
|
||||
>
|
||||
<section className={styles.features}>
|
||||
<div className="container">
|
||||
<section>
|
||||
<h1>Get started with Solana development</h1>
|
||||
|
||||
<div className="container__spacer">
|
||||
<p>
|
||||
Build and deploy your first on chain Solana program directly in
|
||||
your browser.
|
||||
</p>
|
||||
|
||||
<Link to="/getstarted/hello-world">
|
||||
<a className="button">Get Started</a>
|
||||
</Link>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="">
|
||||
<div className="row cards__container">
|
||||
<Card
|
||||
to="/getstarted/hello-world"
|
||||
header={{
|
||||
label: "Hello World in your Browser",
|
||||
translateId: "getstarted-hello",
|
||||
}}
|
||||
body={{
|
||||
label:
|
||||
"Write and deploy your first Solana program directly in your browser. No install needed.",
|
||||
translateId: "getstarted-hello-body",
|
||||
}}
|
||||
/>
|
||||
|
||||
<Card
|
||||
to="/getstarted/local"
|
||||
header={{
|
||||
label: "Local development",
|
||||
translateId: "getstarted-local",
|
||||
}}
|
||||
body={{
|
||||
label:
|
||||
"Setup your local development environment for writing on chain programs.",
|
||||
translateId: "getstarted-c-body",
|
||||
}}
|
||||
/>
|
||||
|
||||
<Card
|
||||
to="/getstarted/rust"
|
||||
header={{
|
||||
label: "Native Rust Program",
|
||||
translateId: "getstarted-rust",
|
||||
}}
|
||||
body={{
|
||||
label:
|
||||
"Build and deploy an on chain Solana program with the Rust language.",
|
||||
translateId: "getstarted-rust-body",
|
||||
}}
|
||||
/>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="">
|
||||
<h2>Community Resources</h2>
|
||||
|
||||
<div className="row cards__container">
|
||||
<Card
|
||||
externalIcon={true}
|
||||
to="https://www.anchor-lang.com/"
|
||||
header={{
|
||||
label: "Anchor Framework",
|
||||
translateId: "getstarted-anchor",
|
||||
}}
|
||||
body={{
|
||||
label: "Rust based framework for writing Solana programs.",
|
||||
translateId: "start-building",
|
||||
}}
|
||||
/>
|
||||
|
||||
<Card
|
||||
externalIcon={true}
|
||||
to="https://seahorse-lang.org/"
|
||||
header={{
|
||||
label: "Seahorse Lang",
|
||||
translateId: "getstarted-seahorse",
|
||||
}}
|
||||
body={{
|
||||
label: "Write Anchor-compatible Solana programs in Python.",
|
||||
translateId: "learn-hello-world",
|
||||
}}
|
||||
/>
|
||||
|
||||
<Card
|
||||
externalIcon={true}
|
||||
to="https://beta.solpg.io/"
|
||||
header={{
|
||||
label: "Solana Playground",
|
||||
translateId: "developer-examples",
|
||||
}}
|
||||
body={{
|
||||
label:
|
||||
"Quickly develop, deploy and test Solana programs from the browser.",
|
||||
translateId: "learn-by-example",
|
||||
}}
|
||||
/>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</section>
|
||||
</CardLayout>
|
||||
);
|
||||
}
|
||||
|
||||
export default GetStartedPage;
|
||||
|
|
@ -30,7 +30,7 @@
|
|||
|
||||
.features {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
align-items: top;
|
||||
padding: 2rem 0;
|
||||
width: 100%;
|
||||
}
|
||||
|
|
@ -39,3 +39,7 @@
|
|||
height: 200px;
|
||||
width: 200px;
|
||||
}
|
||||
|
||||
.iconExternalIcon {
|
||||
margin-left: 0.5em;
|
||||
}
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 214 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 145 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 143 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 171 KiB |
Loading…
Reference in New Issue